diff --git a/.augmentignore b/.augmentignore index a031c5b..101557f 100644 --- a/.augmentignore +++ b/.augmentignore @@ -1 +1 @@ -__reports__/ \ No newline at end of file +__reports__/ diff --git a/.commitlintrc.json b/.commitlintrc.json index eca3a08..18fb2ea 100644 --- a/.commitlintrc.json +++ b/.commitlintrc.json @@ -6,7 +6,7 @@ "always", [ "build", - "chore", + "chore", "ci", "docs", "feat", diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index d39b9dd..b6d5a53 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -48,7 +48,7 @@ body: placeholder: | - OS: (e.g., Ubuntu 22.04, macOS 14.1, Windows 11) - Hatch version: (run `pip show hatch`) - - Python version: + - Python version: - Package manager: (conda/mamba version if applicable) - Current environment: (run `hatch env current`) render: markdown @@ -117,18 +117,18 @@ body: Please run the diagnostic commands from the troubleshooting guide and paste the output: placeholder: | Run these commands and paste the output: - + hatch env list - hatch env current + hatch env current hatch package list pip show hatch - + For environment-specific issues: hatch env python info --hatch_env --detailed - + For registry issues: hatch package add --refresh-registry - + Cache information: ls -la ~/.hatch/cache/packages (Linux/macOS) Get-ChildItem -Path $env:USERPROFILE\.hatch\cache (Windows PowerShell) diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml index bf749a0..eceb860 100644 --- a/.github/ISSUE_TEMPLATE/documentation.yml +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -46,7 +46,7 @@ body: label: Documentation Location description: Where is the documentation issue located? placeholder: | - e.g., README.md, docs/articles/users/CLIReference.md, + e.g., README.md, docs/articles/users/CLIReference.md, docs/articles/users/GettingStarted.md, https://crackingshells.github.io/Hatch/ validations: required: true diff --git a/.github/ISSUE_TEMPLATE/environment_issue.yml b/.github/ISSUE_TEMPLATE/environment_issue.yml index 8a84802..d508aab 100644 --- a/.github/ISSUE_TEMPLATE/environment_issue.yml +++ b/.github/ISSUE_TEMPLATE/environment_issue.yml @@ -56,7 +56,7 @@ body: placeholder: | - OS: (e.g., Ubuntu 22.04, macOS 14.1, Windows 11) - Hatch version: (run `pip show hatch`) - - Python version: + - Python version: - Conda/Mamba version: (run `conda --version` or `mamba --version`) - Available disk space: (run `df -h` on Linux/macOS or check disk space on Windows) render: markdown @@ -95,11 +95,11 @@ body: Please provide current environment information placeholder: | Run these commands and paste the output: - + hatch env list hatch env current hatch env python info --hatch_env --detailed - + For Python environment issues: conda env list (or mamba env list) conda info (or mamba info) @@ -151,11 +151,11 @@ body: If relevant, provide information about the environment directory structure placeholder: | Environment directory location: ~/.hatch/envs/ - + Directory contents: ls -la ~/.hatch/envs// (Linux/macOS) Get-ChildItem ~/.hatch/envs// (Windows PowerShell) - + Python environment location (if applicable): conda env list | grep render: text @@ -169,7 +169,7 @@ body: placeholder: | Run and paste output: hatch package list --env - + For Python environment: conda list -n (or mamba list) render: text diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 8011a72..0ac14f9 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -84,11 +84,11 @@ body: If this feature involves new CLI commands, describe the proposed command structure placeholder: | Propose the command syntax and options: - + hatch package search --filter hatch env clone hatch template list --category - + Include: - Command names and subcommands - Required and optional arguments @@ -121,7 +121,7 @@ body: attributes: label: Implementation Ideas description: | - Do you have any ideas about how this could be implemented? + Do you have any ideas about how this could be implemented? (Optional - only if you have technical insights) placeholder: | If you have ideas about implementation approaches, technical details, or architecture: diff --git a/.github/ISSUE_TEMPLATE/package_issue.yml b/.github/ISSUE_TEMPLATE/package_issue.yml index ddc6f85..e436ef7 100644 --- a/.github/ISSUE_TEMPLATE/package_issue.yml +++ b/.github/ISSUE_TEMPLATE/package_issue.yml @@ -137,7 +137,7 @@ body: ... } ``` - + For validation issues, also include the validation output: hatch validate render: markdown diff --git a/.github/workflows/prerelease-discord-notification.yml b/.github/workflows/prerelease-discord-notification.yml index abdd13e..44e6090 100644 --- a/.github/workflows/prerelease-discord-notification.yml +++ b/.github/workflows/prerelease-discord-notification.yml @@ -18,18 +18,18 @@ jobs: title: "πŸ§ͺ Hatch Pre-release Available for Testing" description: | **Version `${{ github.event.release.tag_name }}`** is now available for testing! - + ⚠️ **This is a pre-release** - expect potential bugs and breaking changes πŸ”¬ Perfect for testing new features and providing feedback πŸ“‹ Click [here](${{ github.event.release.html_url }}) to view what's new and download πŸ’» Install with pip: ```bash - pip install hatch-xclam=${{ github.event.release.tag_name }} + pip install hatch-xclam==${{ github.event.release.tag_name }} ``` - + Help us make *Hatch!* better by testing and reporting [issues](https://github.com/CrackingShells/Hatch/issues)! πŸ›βž‘οΈβœ¨ color: 0xff9500 # Orange color for pre-release username: "Cracking Shells Pre-release Bot" image: "https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/hatch_icon_dark_bg_transparent.png" - avatar_url: "https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/cs_core_dark_bg.png" \ No newline at end of file + avatar_url: "https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/cs_core_dark_bg.png" diff --git a/.github/workflows/release-discord-notification.yml b/.github/workflows/release-discord-notification.yml index 1d46259..fe9261f 100644 --- a/.github/workflows/release-discord-notification.yml +++ b/.github/workflows/release-discord-notification.yml @@ -17,8 +17,8 @@ jobs: content: "<@&1418053865818951721>" title: "πŸŽ‰ New *Hatch!* Release Available!" description: | - **Version `${{ github.event.release.tag_name }}`** has been released! - + **Version `${{ github.event.release.tag_name }}`** has been released! + πŸš€ Get the latest features and improvements πŸ“š Click [here](${{ github.event.release.html_url }}) to view the changelog and download @@ -26,7 +26,7 @@ jobs: ```bash pip install hatch-xclam ``` - + Happy MCP coding with *Hatch!* 🐣 color: 0x00ff88 username: "Cracking Shells Release Bot" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..ebf50e1 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,29 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + exclude: ^mkdocs\.yml$ + - id: check-added-large-files + - id: check-toml + + - repo: https://github.com/psf/black + rev: 23.12.1 + hooks: + - id: black + language_version: python3.12 + + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.1.9 + hooks: + - id: ruff + args: [--fix, --exit-non-zero-on-fix] + + - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook + rev: v9.11.0 + hooks: + - id: commitlint + stages: [commit-msg] + additional_dependencies: ['@commitlint/cli@^18.6.1', '@commitlint/config-conventional@^18.6.2'] diff --git a/CHANGELOG.md b/CHANGELOG.md index a2c1554..2f6d613 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,273 @@ +## 0.8.0-dev.2 (2026-02-20) + +* Merge pull request #45 from LittleCoinCoin/dev ([0ed9010](https://github.com/CrackingShells/Hatch/commit/0ed9010)), closes [#45](https://github.com/CrackingShells/Hatch/issues/45) +* fix(ci): pre-release installation instructions ([0206dc0](https://github.com/CrackingShells/Hatch/commit/0206dc0)) +* fix(cli-version): use correct package name for version lookup ([76c3364](https://github.com/CrackingShells/Hatch/commit/76c3364)) +* fix(cli): remove obsolete handle_mcp_show import ([388ca01](https://github.com/CrackingShells/Hatch/commit/388ca01)) +* fix(instructions): purge stale Phase terminology ([dba119a](https://github.com/CrackingShells/Hatch/commit/dba119a)) +* fix(mcp-adapters): add missing strategies import ([533a66d](https://github.com/CrackingShells/Hatch/commit/533a66d)) +* fix(mcp-adapters): add transport mutual exclusion to GeminiAdapter ([319d067](https://github.com/CrackingShells/Hatch/commit/319d067)) +* fix(mcp-adapters): allow enabled_tools/disabled_tools coexistence ([ea6471c](https://github.com/CrackingShells/Hatch/commit/ea6471c)) +* fix(mcp-adapters): allow includeTools/excludeTools coexistence ([d8f8a56](https://github.com/CrackingShells/Hatch/commit/d8f8a56)) +* fix(mcp-adapters): remove type field rejection from CodexAdapter ([0627352](https://github.com/CrackingShells/Hatch/commit/0627352)) +* fix(mcp-adapters): remove type field rejection from GeminiAdapter ([2d8e0a3](https://github.com/CrackingShells/Hatch/commit/2d8e0a3)) +* fix(ruff): resolve F821 errors and consolidate imports ([0be9fc8](https://github.com/CrackingShells/Hatch/commit/0be9fc8)), closes [hi#priority](https://github.com/hi/issues/priority) +* docs(cli-ref): update mcp sync command documentation ([17ae770](https://github.com/CrackingShells/Hatch/commit/17ae770)) +* docs(mcp-adapters): update architecture for new pattern ([693665c](https://github.com/CrackingShells/Hatch/commit/693665c)) +* docs(mcp): update error message examples ([5988b3a](https://github.com/CrackingShells/Hatch/commit/5988b3a)) +* docs(testing): add tests/README.md with testing strategy ([08162ce](https://github.com/CrackingShells/Hatch/commit/08162ce)) +* docs(testing): update README - all test issues resolved ([5c60ef2](https://github.com/CrackingShells/Hatch/commit/5c60ef2)) +* test(docker-loader): mock docker and online package loader tests ([df5533e](https://github.com/CrackingShells/Hatch/commit/df5533e)) +* test(env-manager): mock conda/mamba detection tests ([ce82350](https://github.com/CrackingShells/Hatch/commit/ce82350)) +* test(env-manager): mock environment creation tests ([8bf3289](https://github.com/CrackingShells/Hatch/commit/8bf3289)) +* test(env-manager): mock remaining integration tests ([5a4d215](https://github.com/CrackingShells/Hatch/commit/5a4d215)) +* test(env-manip): mock advanced package dependency tests ([1878751](https://github.com/CrackingShells/Hatch/commit/1878751)) +* test(env-manip): mock advanced package dependency tests ([9a945ad](https://github.com/CrackingShells/Hatch/commit/9a945ad)) +* test(env-manip): mock basic environment operations ([0b4ed74](https://github.com/CrackingShells/Hatch/commit/0b4ed74)) +* test(env-manip): mock basic environment operations ([675a67d](https://github.com/CrackingShells/Hatch/commit/675a67d)) +* test(env-manip): mock package addition tests ([0f99f4c](https://github.com/CrackingShells/Hatch/commit/0f99f4c)) +* test(env-manip): mock package addition tests ([04cb79f](https://github.com/CrackingShells/Hatch/commit/04cb79f)) +* test(env-manip): mock remaining 3 slow tests ([df7517c](https://github.com/CrackingShells/Hatch/commit/df7517c)) +* test(env-manip): mock system, docker, and MCP server tests ([63084c4](https://github.com/CrackingShells/Hatch/commit/63084c4)) +* test(env-manip): mock system, docker, and MCP server tests ([9487ef8](https://github.com/CrackingShells/Hatch/commit/9487ef8)) +* test(env-manip): remove remaining @slow_test decorators ([0403a7d](https://github.com/CrackingShells/Hatch/commit/0403a7d)) +* test(installer): add shared venv fixture for integration tests ([095f6ce](https://github.com/CrackingShells/Hatch/commit/095f6ce)) +* test(installer): mock pip installation tests (batch 1) ([45bdae0](https://github.com/CrackingShells/Hatch/commit/45bdae0)) +* test(installer): mock pip installation tests (batch 2) ([1650442](https://github.com/CrackingShells/Hatch/commit/1650442)) +* test(installer): refactor integration test to use shared venv ([bd979be](https://github.com/CrackingShells/Hatch/commit/bd979be)) +* test(mcp-adapters): add canonical configs fixture ([46f54a6](https://github.com/CrackingShells/Hatch/commit/46f54a6)) +* test(mcp-adapters): add cross-host sync tests (64 pairs) ([c77f448](https://github.com/CrackingShells/Hatch/commit/c77f448)) +* test(mcp-adapters): add field filtering regression tests ([bc3e631](https://github.com/CrackingShells/Hatch/commit/bc3e631)) +* test(mcp-adapters): add host configuration tests (8 hosts) ([b3e640e](https://github.com/CrackingShells/Hatch/commit/b3e640e)) +* test(mcp-adapters): add validation bug regression tests ([8eb6f7a](https://github.com/CrackingShells/Hatch/commit/8eb6f7a)) +* test(mcp-adapters): deprecate old tests for data-driven ([8177520](https://github.com/CrackingShells/Hatch/commit/8177520)) +* test(mcp-adapters): fix registry test for new abstract method ([32aa3cb](https://github.com/CrackingShells/Hatch/commit/32aa3cb)) +* test(mcp-adapters): implement HostRegistry with fields.py ([127c1f7](https://github.com/CrackingShells/Hatch/commit/127c1f7)) +* test(mcp-adapters): implement property-based assertions ([4ac17ef](https://github.com/CrackingShells/Hatch/commit/4ac17ef)) +* test(mcp-sync): use canonical fixture data in detailed flag tests ([c2f35e4](https://github.com/CrackingShells/Hatch/commit/c2f35e4)) +* test(non-tty): remove slow_test from integration tests ([772de01](https://github.com/CrackingShells/Hatch/commit/772de01)) +* test(system-installer): mock system installer tests ([23de568](https://github.com/CrackingShells/Hatch/commit/23de568)) +* test(validation): add pytest pythonpath config ([9924374](https://github.com/CrackingShells/Hatch/commit/9924374)) +* feat(cli): display server list in mcp sync pre-prompt ([96d7f56](https://github.com/CrackingShells/Hatch/commit/96d7f56)) +* feat(mcp-adapters): implement field transformations in CodexAdapter ([59cc931](https://github.com/CrackingShells/Hatch/commit/59cc931)) +* feat(mcp-sync): add --detailed flag for field-level sync output ([dea1541](https://github.com/CrackingShells/Hatch/commit/dea1541)) +* feat(mcp): add preview_sync method for server name resolution ([52bdc10](https://github.com/CrackingShells/Hatch/commit/52bdc10)) +* refactor(cli): standardize backup restore failure error ([9a8377f](https://github.com/CrackingShells/Hatch/commit/9a8377f)) +* refactor(cli): standardize configure failure error ([1065c32](https://github.com/CrackingShells/Hatch/commit/1065c32)) +* refactor(cli): standardize mcp sync failure error reporting ([82a2d3b](https://github.com/CrackingShells/Hatch/commit/82a2d3b)) +* refactor(cli): standardize package configure exception warning ([b1bde91](https://github.com/CrackingShells/Hatch/commit/b1bde91)) +* refactor(cli): standardize package configure failure warning ([b14e9f4](https://github.com/CrackingShells/Hatch/commit/b14e9f4)) +* refactor(cli): standardize package invalid host error ([7f448a1](https://github.com/CrackingShells/Hatch/commit/7f448a1)) +* refactor(cli): standardize remove failure error ([023c64f](https://github.com/CrackingShells/Hatch/commit/023c64f)) +* refactor(cli): standardize remove-host failure error ([b2de533](https://github.com/CrackingShells/Hatch/commit/b2de533)) +* refactor(cli): standardize remove-server failure error ([2d40d09](https://github.com/CrackingShells/Hatch/commit/2d40d09)) +* refactor(mcp-adapters): add validate_filtered to BaseAdapter ([b1f542a](https://github.com/CrackingShells/Hatch/commit/b1f542a)) +* refactor(mcp-adapters): convert ClaudeAdapter to validate-after-filter ([13933a5](https://github.com/CrackingShells/Hatch/commit/13933a5)) +* refactor(mcp-adapters): convert CodexAdapter to validate-after-filter ([7ac8de1](https://github.com/CrackingShells/Hatch/commit/7ac8de1)) +* refactor(mcp-adapters): convert CursorAdapter to validate-after-filter ([93aa631](https://github.com/CrackingShells/Hatch/commit/93aa631)) +* refactor(mcp-adapters): convert GeminiAdapter to validate-after-filter ([cb5d98e](https://github.com/CrackingShells/Hatch/commit/cb5d98e)) +* refactor(mcp-adapters): convert KiroAdapter to validate-after-filter ([0eb7d46](https://github.com/CrackingShells/Hatch/commit/0eb7d46)) +* refactor(mcp-adapters): convert LMStudioAdapter to validate-after-filter ([1bd3780](https://github.com/CrackingShells/Hatch/commit/1bd3780)) +* refactor(mcp-adapters): convert VSCodeAdapter to validate-after-filter ([5c78df9](https://github.com/CrackingShells/Hatch/commit/5c78df9)) +* chore(dev-infra): add code quality tools to dev dependencies ([f76c5c1](https://github.com/CrackingShells/Hatch/commit/f76c5c1)) +* chore(dev-infra): add pre-commit configuration ([67da239](https://github.com/CrackingShells/Hatch/commit/67da239)) +* chore(dev-infra): apply black formatting to entire codebase ([2daa89d](https://github.com/CrackingShells/Hatch/commit/2daa89d)) +* chore(dev-infra): apply ruff linting fixes to codebase ([6681ee6](https://github.com/CrackingShells/Hatch/commit/6681ee6)) +* chore(dev-infra): install pre-commit hooks and document initial state ([eb81ea4](https://github.com/CrackingShells/Hatch/commit/eb81ea4)) +* chore(dev-infra): verify pre-commit hooks pass on entire codebase ([ed90350](https://github.com/CrackingShells/Hatch/commit/ed90350)) + +## 0.8.0-dev.1 (2026-02-04) + +* Merge pull request #44 from LittleCoinCoin/dev ([1157922](https://github.com/CrackingShells/Hatch/commit/1157922)), closes [#44](https://github.com/CrackingShells/Hatch/issues/44) +* chore: update entry point to hatch.cli module ([cf81671](https://github.com/CrackingShells/Hatch/commit/cf81671)) +* chore: update submodule `cracking-shells-playbook` ([222b357](https://github.com/CrackingShells/Hatch/commit/222b357)) +* chore(deps): add pytest to dev dependencies ([2761afe](https://github.com/CrackingShells/Hatch/commit/2761afe)) +* chore(docs): remove deprecated CLI api doc ([12a22c0](https://github.com/CrackingShells/Hatch/commit/12a22c0)) +* chore(docs): remove deprecated MCP documentation files ([5ca09a3](https://github.com/CrackingShells/Hatch/commit/5ca09a3)) +* chore(tests): remove deprecated MCP test files ([29a5ec5](https://github.com/CrackingShells/Hatch/commit/29a5ec5)) +* fix(backup): support different config filenames in backup listing ([06eb53a](https://github.com/CrackingShells/Hatch/commit/06eb53a)), closes [#2](https://github.com/CrackingShells/Hatch/issues/2) +* fix(docs): add missing return type annotations for mkdocs build ([da78682](https://github.com/CrackingShells/Hatch/commit/da78682)) +* docs: fix broken link in MCP host configuration architecture ([e9f89f1](https://github.com/CrackingShells/Hatch/commit/e9f89f1)) +* docs(api): restructure CLI API documentation to modular architecture ([318d212](https://github.com/CrackingShells/Hatch/commit/318d212)) +* docs(cli-ref): mark package list as deprecated and update filters ([06f5b75](https://github.com/CrackingShells/Hatch/commit/06f5b75)) +* docs(cli-ref): update environment commands section ([749d992](https://github.com/CrackingShells/Hatch/commit/749d992)) +* docs(cli-ref): update MCP commands section with new list/show commands ([1c812fd](https://github.com/CrackingShells/Hatch/commit/1c812fd)) +* docs(cli): add module docstrings for refactored CLI ([8d7de20](https://github.com/CrackingShells/Hatch/commit/8d7de20)) +* docs(cli): update documentation for handler-based architecture ([f95c5d0](https://github.com/CrackingShells/Hatch/commit/f95c5d0)) +* docs(devs): add CLI architecture and implementation guide ([a3152e1](https://github.com/CrackingShells/Hatch/commit/a3152e1)) +* docs(guide): add quick reference for viewing commands ([5bf5d01](https://github.com/CrackingShells/Hatch/commit/5bf5d01)) +* docs(guide): add viewing host configurations section ([6c381d1](https://github.com/CrackingShells/Hatch/commit/6c381d1)) +* docs(mcp-host-config): deprecate legacy architecture doc ([d8618a5](https://github.com/CrackingShells/Hatch/commit/d8618a5)) +* docs(mcp-host-config): deprecate legacy extension guide ([f172a51](https://github.com/CrackingShells/Hatch/commit/f172a51)) +* docs(mcp-host-config): write new architecture documentation ([ff05ad5](https://github.com/CrackingShells/Hatch/commit/ff05ad5)) +* docs(mcp-host-config): write new extension guide ([7821062](https://github.com/CrackingShells/Hatch/commit/7821062)) +* docs(mcp-reporting): document metadata field exclusion behavior ([5ccb7f9](https://github.com/CrackingShells/Hatch/commit/5ccb7f9)) +* docs(tutorial): fix command syntax in environment sync tutorial ([b2f40bf](https://github.com/CrackingShells/Hatch/commit/b2f40bf)) +* docs(tutorial): fix verification commands in checkpoint tutorial ([59b2485](https://github.com/CrackingShells/Hatch/commit/59b2485)) +* docs(tutorial): update env list output in create environment tutorial ([443607c](https://github.com/CrackingShells/Hatch/commit/443607c)) +* docs(tutorial): update package installation tutorial outputs ([588bab3](https://github.com/CrackingShells/Hatch/commit/588bab3)) +* docs(tutorials): fix command syntax in 04-mcp-host-configuration ([2ac1058](https://github.com/CrackingShells/Hatch/commit/2ac1058)) +* docs(tutorials): fix outdated env list output format in 02-environments ([d38ae24](https://github.com/CrackingShells/Hatch/commit/d38ae24)) +* docs(tutorials): fix validation output in 03-author-package ([776d40f](https://github.com/CrackingShells/Hatch/commit/776d40f)) +* refactor(cli): add deprecation warning to cli_hatch shim ([f9adf0a](https://github.com/CrackingShells/Hatch/commit/f9adf0a)) +* refactor(cli): create cli package structure ([bc80e29](https://github.com/CrackingShells/Hatch/commit/bc80e29)) +* refactor(cli): deprecate `mcp discover servers` and `package list` ([9ce5be0](https://github.com/CrackingShells/Hatch/commit/9ce5be0)) +* refactor(cli): extract argument parsing and implement clean routing ([efeae24](https://github.com/CrackingShells/Hatch/commit/efeae24)) +* refactor(cli): extract environment handlers to cli_env ([d00959f](https://github.com/CrackingShells/Hatch/commit/d00959f)) +* refactor(cli): extract handle_mcp_configure to cli_mcp ([9b9bc4d](https://github.com/CrackingShells/Hatch/commit/9b9bc4d)) +* refactor(cli): extract handle_mcp_sync to cli_mcp ([f69be90](https://github.com/CrackingShells/Hatch/commit/f69be90)) +* refactor(cli): extract MCP backup handlers to cli_mcp ([ca65e2b](https://github.com/CrackingShells/Hatch/commit/ca65e2b)) +* refactor(cli): extract MCP discovery handlers to cli_mcp ([887b96e](https://github.com/CrackingShells/Hatch/commit/887b96e)) +* refactor(cli): extract MCP list handlers to cli_mcp ([e518e90](https://github.com/CrackingShells/Hatch/commit/e518e90)) +* refactor(cli): extract MCP remove handlers to cli_mcp ([4e84be7](https://github.com/CrackingShells/Hatch/commit/4e84be7)) +* refactor(cli): extract package handlers to cli_package ([ebecb1e](https://github.com/CrackingShells/Hatch/commit/ebecb1e)) +* refactor(cli): extract shared utilities to cli_utils ([0b0dc92](https://github.com/CrackingShells/Hatch/commit/0b0dc92)) +* refactor(cli): extract system handlers to cli_system ([2f7d715](https://github.com/CrackingShells/Hatch/commit/2f7d715)) +* refactor(cli): integrate backup path into ResultReporter ([fd9a1f4](https://github.com/CrackingShells/Hatch/commit/fd9a1f4)) +* refactor(cli): integrate sync statistics into ResultReporter ([cc5a8b2](https://github.com/CrackingShells/Hatch/commit/cc5a8b2)) +* refactor(cli): normalize cli_utils warning messages ([6e9b983](https://github.com/CrackingShells/Hatch/commit/6e9b983)) +* refactor(cli): normalize MCP warning messages ([b72c6a4](https://github.com/CrackingShells/Hatch/commit/b72c6a4)) +* refactor(cli): normalize operation cancelled messages ([ab0b611](https://github.com/CrackingShells/Hatch/commit/ab0b611)) +* refactor(cli): normalize package warning messages ([c7463b3](https://github.com/CrackingShells/Hatch/commit/c7463b3)) +* refactor(cli): remove --pattern from mcp list servers ([b8baef9](https://github.com/CrackingShells/Hatch/commit/b8baef9)) +* refactor(cli): remove legacy mcp show command ([fd2c290](https://github.com/CrackingShells/Hatch/commit/fd2c290)) +* refactor(cli): rewrite mcp list hosts for host-centric design ([ac88a84](https://github.com/CrackingShells/Hatch/commit/ac88a84)) +* refactor(cli): rewrite mcp list servers for host-centric design ([c2de727](https://github.com/CrackingShells/Hatch/commit/c2de727)) +* refactor(cli): simplify CLI to use unified MCPServerConfig with adapters ([d97b99e](https://github.com/CrackingShells/Hatch/commit/d97b99e)) +* refactor(cli): simplify env list to show package count only ([3045718](https://github.com/CrackingShells/Hatch/commit/3045718)) +* refactor(cli): update env execution errors to use report_error ([8021ba2](https://github.com/CrackingShells/Hatch/commit/8021ba2)) +* refactor(cli): update env validation error to use ValidationError ([101eba7](https://github.com/CrackingShells/Hatch/commit/101eba7)) +* refactor(cli): update MCP exception handlers to use report_error ([edec31d](https://github.com/CrackingShells/Hatch/commit/edec31d)) +* refactor(cli): update MCP validation errors to use ValidationError ([20b165a](https://github.com/CrackingShells/Hatch/commit/20b165a)) +* refactor(cli): update package errors to use report_error ([4d0ab73](https://github.com/CrackingShells/Hatch/commit/4d0ab73)) +* refactor(cli): update system errors to use report_error ([b205032](https://github.com/CrackingShells/Hatch/commit/b205032)) +* refactor(cli): use HatchArgumentParser for all parsers ([4b750fa](https://github.com/CrackingShells/Hatch/commit/4b750fa)) +* refactor(cli): use ResultReporter in env create/remove handlers ([d0991ba](https://github.com/CrackingShells/Hatch/commit/d0991ba)) +* refactor(cli): use ResultReporter in env python handlers ([df14f66](https://github.com/CrackingShells/Hatch/commit/df14f66)) +* refactor(cli): use ResultReporter in handle_env_python_add_hatch_mcp ([0ec6b6a](https://github.com/CrackingShells/Hatch/commit/0ec6b6a)) +* refactor(cli): use ResultReporter in handle_env_use ([b7536fb](https://github.com/CrackingShells/Hatch/commit/b7536fb)) +* refactor(cli): use ResultReporter in handle_mcp_configure ([5f3c60c](https://github.com/CrackingShells/Hatch/commit/5f3c60c)) +* refactor(cli): use ResultReporter in handle_mcp_sync ([9d52d24](https://github.com/CrackingShells/Hatch/commit/9d52d24)) +* refactor(cli): use ResultReporter in handle_package_add ([49585fa](https://github.com/CrackingShells/Hatch/commit/49585fa)) +* refactor(cli): use ResultReporter in handle_package_remove ([58ffdf1](https://github.com/CrackingShells/Hatch/commit/58ffdf1)) +* refactor(cli): use ResultReporter in handle_package_sync ([987b9d1](https://github.com/CrackingShells/Hatch/commit/987b9d1)) +* refactor(cli): use ResultReporter in MCP backup handlers ([9ec9e7b](https://github.com/CrackingShells/Hatch/commit/9ec9e7b)) +* refactor(cli): use ResultReporter in MCP remove handlers ([e727324](https://github.com/CrackingShells/Hatch/commit/e727324)) +* refactor(cli): use ResultReporter in system handlers ([df64898](https://github.com/CrackingShells/Hatch/commit/df64898)) +* refactor(cli): use TableFormatter in handle_env_list ([0f18682](https://github.com/CrackingShells/Hatch/commit/0f18682)) +* refactor(cli): use TableFormatter in handle_mcp_backup_list ([17dd96a](https://github.com/CrackingShells/Hatch/commit/17dd96a)) +* refactor(cli): use TableFormatter in handle_mcp_discover_hosts ([6bef0fa](https://github.com/CrackingShells/Hatch/commit/6bef0fa)) +* refactor(cli): use TableFormatter in handle_mcp_list_hosts ([3b465bb](https://github.com/CrackingShells/Hatch/commit/3b465bb)) +* refactor(cli): use TableFormatter in handle_mcp_list_servers ([3145e47](https://github.com/CrackingShells/Hatch/commit/3145e47)) +* refactor(mcp-host-config): unified MCPServerConfig ([ca0e51c](https://github.com/CrackingShells/Hatch/commit/ca0e51c)) +* refactor(mcp-host-config): update module exports ([5371a43](https://github.com/CrackingShells/Hatch/commit/5371a43)) +* refactor(mcp-host-config): wire all strategies to use adapters ([528e5f5](https://github.com/CrackingShells/Hatch/commit/528e5f5)) +* refactor(mcp): deprecate display_report in favor of ResultReporter ([3880ea3](https://github.com/CrackingShells/Hatch/commit/3880ea3)) +* refactor(models): remove legacy host-specific models from models.py ([ff92280](https://github.com/CrackingShells/Hatch/commit/ff92280)) +* feat(adapters): create AdapterRegistry for host-adapter mapping ([a8e3dfb](https://github.com/CrackingShells/Hatch/commit/a8e3dfb)) +* feat(adapters): create BaseAdapter abstract class ([4d9833c](https://github.com/CrackingShells/Hatch/commit/4d9833c)) +* feat(adapters): create host-specific adapters ([7b725c8](https://github.com/CrackingShells/Hatch/commit/7b725c8)) +* feat(cli): add --dry-run to env and package commands ([4a0f3e5](https://github.com/CrackingShells/Hatch/commit/4a0f3e5)) +* feat(cli): add --dry-run to env use, package add, create commands ([79da44c](https://github.com/CrackingShells/Hatch/commit/79da44c)) +* feat(cli): add --host and --pattern flags to mcp list servers ([29f86aa](https://github.com/CrackingShells/Hatch/commit/29f86aa)) +* feat(cli): add --json flag to list commands ([73f62ed](https://github.com/CrackingShells/Hatch/commit/73f62ed)) +* feat(cli): add --pattern filter to env list ([6deff84](https://github.com/CrackingShells/Hatch/commit/6deff84)) +* feat(cli): add Color, ConsequenceType, Consequence, ResultReporter ([10cdb71](https://github.com/CrackingShells/Hatch/commit/10cdb71)) +* feat(cli): add confirmation prompt to env remove ([b1156e7](https://github.com/CrackingShells/Hatch/commit/b1156e7)) +* feat(cli): add confirmation prompt to package remove ([38d9051](https://github.com/CrackingShells/Hatch/commit/38d9051)) +* feat(cli): add ConversionReport to ResultReporter bridge ([4ea999e](https://github.com/CrackingShells/Hatch/commit/4ea999e)) +* feat(cli): add format_info utility ([b1f33d4](https://github.com/CrackingShells/Hatch/commit/b1f33d4)) +* feat(cli): add format_validation_error utility ([f28b841](https://github.com/CrackingShells/Hatch/commit/f28b841)) +* feat(cli): add format_warning utility ([28ec610](https://github.com/CrackingShells/Hatch/commit/28ec610)) +* feat(cli): add hatch env show command ([2bc96bc](https://github.com/CrackingShells/Hatch/commit/2bc96bc)) +* feat(cli): add hatch mcp show command ([9ab53bc](https://github.com/CrackingShells/Hatch/commit/9ab53bc)) +* feat(cli): add HatchArgumentParser with formatted errors ([1fb7006](https://github.com/CrackingShells/Hatch/commit/1fb7006)) +* feat(cli): add highlight utility for entity names ([c25631a](https://github.com/CrackingShells/Hatch/commit/c25631a)) +* feat(cli): add parser for env list hosts command ([a218dea](https://github.com/CrackingShells/Hatch/commit/a218dea)) +* feat(cli): add parser for env list servers command ([851c866](https://github.com/CrackingShells/Hatch/commit/851c866)) +* feat(cli): add parser for mcp show hosts command ([f7abe61](https://github.com/CrackingShells/Hatch/commit/f7abe61)) +* feat(cli): add report_error method to ResultReporter ([e0f89e1](https://github.com/CrackingShells/Hatch/commit/e0f89e1)) +* feat(cli): add report_partial_success method to ResultReporter ([1ce4fd9](https://github.com/CrackingShells/Hatch/commit/1ce4fd9)) +* feat(cli): add TableFormatter for aligned table output ([658f48a](https://github.com/CrackingShells/Hatch/commit/658f48a)) +* feat(cli): add true color terminal detection ([aa76bfc](https://github.com/CrackingShells/Hatch/commit/aa76bfc)) +* feat(cli): add unicode terminal detection ([91d7c30](https://github.com/CrackingShells/Hatch/commit/91d7c30)) +* feat(cli): add ValidationError exception class ([af63b46](https://github.com/CrackingShells/Hatch/commit/af63b46)) +* feat(cli): implement env list hosts command ([bebe6ab](https://github.com/CrackingShells/Hatch/commit/bebe6ab)) +* feat(cli): implement env list servers command ([0c7a744](https://github.com/CrackingShells/Hatch/commit/0c7a744)) +* feat(cli): implement HCL color palette with true color support ([d70b4f2](https://github.com/CrackingShells/Hatch/commit/d70b4f2)) +* feat(cli): implement mcp show hosts command ([2c716bb](https://github.com/CrackingShells/Hatch/commit/2c716bb)) +* feat(cli): implement mcp show servers command ([e6df7b4](https://github.com/CrackingShells/Hatch/commit/e6df7b4)) +* feat(cli): update mcp list hosts JSON output ([a6f5994](https://github.com/CrackingShells/Hatch/commit/a6f5994)) +* feat(cli): update mcp list hosts parser with --server flag ([c298d52](https://github.com/CrackingShells/Hatch/commit/c298d52)) +* feat(mcp-host-config): add field support constants ([1e81a24](https://github.com/CrackingShells/Hatch/commit/1e81a24)) +* feat(mcp-host-config): add transport detection to MCPServerConfig ([c4eabd2](https://github.com/CrackingShells/Hatch/commit/c4eabd2)) +* feat(mcp-host-config): implement LMStudioAdapter ([0662b14](https://github.com/CrackingShells/Hatch/commit/0662b14)) +* feat(mcp-reporting): metadata fields exclusion from cli reports ([41db3da](https://github.com/CrackingShells/Hatch/commit/41db3da)) +* test(cli): add ConversionReport fixtures for reporter tests ([eeccff6](https://github.com/CrackingShells/Hatch/commit/eeccff6)) +* test(cli): add failing integration test for MCP handler ([acf7c94](https://github.com/CrackingShells/Hatch/commit/acf7c94)) +* test(cli): add failing test for host-centric mcp list servers ([0fcb8fd](https://github.com/CrackingShells/Hatch/commit/0fcb8fd)) +* test(cli): add failing tests for ConversionReport integration ([8e6efc0](https://github.com/CrackingShells/Hatch/commit/8e6efc0)) +* test(cli): add failing tests for env list hosts ([454b0e4](https://github.com/CrackingShells/Hatch/commit/454b0e4)) +* test(cli): add failing tests for env list servers ([7250387](https://github.com/CrackingShells/Hatch/commit/7250387)) +* test(cli): add failing tests for host-centric mcp list hosts ([3ec0617](https://github.com/CrackingShells/Hatch/commit/3ec0617)) +* test(cli): add failing tests for mcp show hosts ([8c8f3e9](https://github.com/CrackingShells/Hatch/commit/8c8f3e9)) +* test(cli): add failing tests for mcp show servers ([fac85fe](https://github.com/CrackingShells/Hatch/commit/fac85fe)) +* test(cli): add failing tests for TableFormatter ([90f3953](https://github.com/CrackingShells/Hatch/commit/90f3953)) +* test(cli): add test directory structure for CLI reporter ([7044b47](https://github.com/CrackingShells/Hatch/commit/7044b47)) +* test(cli): add test utilities for handler testing ([55322c7](https://github.com/CrackingShells/Hatch/commit/55322c7)) +* test(cli): add tests for Color enum and color enable/disable logic ([f854324](https://github.com/CrackingShells/Hatch/commit/f854324)) +* test(cli): add tests for Consequence dataclass and ResultReporter ([127575d](https://github.com/CrackingShells/Hatch/commit/127575d)) +* test(cli): add tests for ConsequenceType enum ([a3f0204](https://github.com/CrackingShells/Hatch/commit/a3f0204)) +* test(cli): add tests for error reporting methods ([2561532](https://github.com/CrackingShells/Hatch/commit/2561532)) +* test(cli): add tests for HatchArgumentParser ([8b192e5](https://github.com/CrackingShells/Hatch/commit/8b192e5)) +* test(cli): add tests for ValidationError and utilities ([a2a5c29](https://github.com/CrackingShells/Hatch/commit/a2a5c29)) +* test(cli): add true color detection tests ([79f6faa](https://github.com/CrackingShells/Hatch/commit/79f6faa)) +* test(cli): update backup tests for cli_mcp module ([8174bef](https://github.com/CrackingShells/Hatch/commit/8174bef)) +* test(cli): update color tests for HCL palette ([a19780c](https://github.com/CrackingShells/Hatch/commit/a19780c)) +* test(cli): update direct_management tests for cli_mcp module ([16f8520](https://github.com/CrackingShells/Hatch/commit/16f8520)) +* test(cli): update discovery tests for cli_mcp module ([de75cf0](https://github.com/CrackingShells/Hatch/commit/de75cf0)) +* test(cli): update for new cli architecture ([64cf74e](https://github.com/CrackingShells/Hatch/commit/64cf74e)) +* test(cli): update host config integration tests for cli_mcp module ([ea5c6b6](https://github.com/CrackingShells/Hatch/commit/ea5c6b6)) +* test(cli): update host_specific_args tests for cli_mcp module ([8f477f6](https://github.com/CrackingShells/Hatch/commit/8f477f6)) +* test(cli): update list tests for cli_mcp module ([e21ecc0](https://github.com/CrackingShells/Hatch/commit/e21ecc0)) +* test(cli): update mcp list servers tests for --pattern removal ([9bb5fe5](https://github.com/CrackingShells/Hatch/commit/9bb5fe5)) +* test(cli): update partial_updates tests for cli_mcp module ([4484e67](https://github.com/CrackingShells/Hatch/commit/4484e67)) +* test(cli): update remaining MCP tests for cli_mcp module ([a655775](https://github.com/CrackingShells/Hatch/commit/a655775)) +* test(cli): update sync_functionality tests for cli_mcp module ([eeb2d6d](https://github.com/CrackingShells/Hatch/commit/eeb2d6d)) +* test(cli): update tests for cli_utils module ([7d72f76](https://github.com/CrackingShells/Hatch/commit/7d72f76)) +* test(cli): update tests for mcp show removal ([a0e730b](https://github.com/CrackingShells/Hatch/commit/a0e730b)) +* test(deprecate): rename 28 legacy MCP tests to .bak for rebuild ([e7f9c50](https://github.com/CrackingShells/Hatch/commit/e7f9c50)) +* test(mcp-host-config): add adapter registry unit tests ([bc8f455](https://github.com/CrackingShells/Hatch/commit/bc8f455)) +* test(mcp-host-config): add integration tests for adapter serialization ([6910120](https://github.com/CrackingShells/Hatch/commit/6910120)) +* test(mcp-host-config): add regression tests for field filtering ([d6ce817](https://github.com/CrackingShells/Hatch/commit/d6ce817)) +* test(mcp-host-config): add unit tests ([c1a0fa4](https://github.com/CrackingShells/Hatch/commit/c1a0fa4)) +* test(mcp-host-config): create three-tier test directory structure ([d78681b](https://github.com/CrackingShells/Hatch/commit/d78681b)) +* test(mcp-host-config): update integration tests for adapter architecture ([acd7871](https://github.com/CrackingShells/Hatch/commit/acd7871)) + + +### BREAKING CHANGE + +* Remove all legacy host-specific configuration models +that are now replaced by the unified adapter architecture. + +Removed models: +- MCPServerConfigBase (abstract base class) +- MCPServerConfigGemini +- MCPServerConfigVSCode +- MCPServerConfigCursor +- MCPServerConfigClaude +- MCPServerConfigKiro +- MCPServerConfigCodex +- MCPServerConfigOmni +- HOST_MODEL_REGISTRY + +The unified MCPServerConfig model plus host-specific adapters now +handle all MCP server configuration. See: +- hatch/mcp_host_config/adapters/ for host adapters + +This is part of Milestone 3.1: Legacy Removal in the adapter architecture +refactoring. Tests will need to be updated in subsequent commits. + ## 0.7.1 (2025-12-22) * Merge pull request #43 from CrackingShells/dev ([b8093b5](https://github.com/CrackingShells/Hatch/commit/b8093b5)), closes [#43](https://github.com/CrackingShells/Hatch/issues/43) diff --git a/__reports__/CLI-refactoring/05-documentation_deprecation_analysis_v0.md b/__reports__/CLI-refactoring/05-documentation_deprecation_analysis_v0.md new file mode 100644 index 0000000..c552c7e --- /dev/null +++ b/__reports__/CLI-refactoring/05-documentation_deprecation_analysis_v0.md @@ -0,0 +1,194 @@ +# Documentation Deprecation Analysis: CLI Refactoring Impact + +**Date**: 2026-01-01 +**Phase**: Post-Implementation Documentation Review +**Scope**: Identifying deprecated documentation after CLI handler-based architecture refactoring +**Reference**: `__design__/cli-refactoring-milestone-v0.7.2-dev.1.md` + +--- + +## Executive Summary + +The CLI refactoring from monolithic `cli_hatch.py` (2,850 LOC) to handler-based architecture in `hatch/cli/` package has rendered several documentation references outdated. This report identifies affected files and specifies required updates. + +**Architecture Change Summary:** +``` +BEFORE: AFTER: +hatch/cli_hatch.py (2,850 LOC) hatch/cli/ + β”œβ”€β”€ __init__.py (57 LOC) + β”œβ”€β”€ __main__.py (840 LOC) + β”œβ”€β”€ cli_utils.py (270 LOC) + β”œβ”€β”€ cli_mcp.py (1,222 LOC) + β”œβ”€β”€ cli_env.py (375 LOC) + β”œβ”€β”€ cli_package.py (552 LOC) + └── cli_system.py (92 LOC) + + hatch/cli_hatch.py (136 LOC) ← backward compat shim +``` + +--- + +## Affected Documentation Files + +### Category 1: API Documentation (HIGH PRIORITY) + +| File | Issue | Impact | +|------|-------|--------| +| `docs/articles/api/cli.md` | References `hatch.cli_hatch` only | mkdocstrings generates incomplete API docs | + +**Current Content:** +```markdown +# CLI Module +::: hatch.cli_hatch +``` + +**Required Update:** Expand to document the full `hatch.cli` package structure with all submodules. + +--- + +### Category 2: User Documentation (HIGH PRIORITY) + +| File | Line | Issue | +|------|------|-------| +| `docs/articles/users/CLIReference.md` | 3 | States "implemented in `hatch/cli_hatch.py`" | + +**Current Content (Line 3):** +```markdown +This document is a compact reference of all Hatch CLI commands and options implemented in `hatch/cli_hatch.py` presented as tables for quick lookup. +``` + +**Required Update:** Reference the new `hatch/cli/` package structure. + +--- + +### Category 3: Developer Implementation Guides (HIGH PRIORITY) + +| File | Lines | Issue | +|------|-------|-------| +| `docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md` | 605, 613-626 | References `cli_hatch.py` for CLI integration | + +**Affected Sections:** + +1. **Line 605** - "Add CLI arguments in `cli_hatch.py`" +2. **Lines 613-626** - CLI Integration for Host-Specific Fields section + +**Current Content:** +```markdown +4. **Add CLI arguments** in `cli_hatch.py` (see next section) +... +1. **Update function signature** in `handle_mcp_configure()`: +```python +def handle_mcp_configure( + # ... existing params ... + your_field: Optional[str] = None, # Add your field +): +``` +``` + +**Required Update:** +- Argument parsing β†’ `hatch/cli/__main__.py` +- Handler modifications β†’ `hatch/cli/cli_mcp.py` + +--- + +### Category 4: Architecture Documentation (MEDIUM PRIORITY) + +| File | Line | Issue | +|------|------|-------| +| `docs/articles/devs/architecture/mcp_host_configuration.md` | 158 | References `cli_hatch.py` | + +**Current Content (Line 158):** +```markdown +1. Extend `handle_mcp_configure()` function signature in `cli_hatch.py` +``` + +**Required Update:** Reference new module locations. + +--- + +### Category 5: Architecture Diagrams (MEDIUM PRIORITY) + +| File | Line | Issue | +|------|------|-------| +| `docs/resources/diagrams/architecture.puml` | 9 | Shows CLI as single `cli_hatch` component | + +**Current Content:** +```plantuml +Container_Boundary(cli, "CLI Layer") { + Component(cli_hatch, "CLI Interface", "Python", "Command-line interface\nArgument parsing and validation") +} +``` + +**Required Update:** Reflect modular CLI architecture with handler modules. + +--- + +### Category 6: Instruction Templates (LOW PRIORITY) + +| File | Lines | Issue | +|------|-------|-------| +| `cracking-shells-playbook/instructions/documentation-api.instructions.md` | 37-41 | Uses `hatch/cli_hatch.py` as example | + +**Current Content:** +```markdown +**For a module `hatch/cli_hatch.py`, create `docs/articles/api/cli.md`:** +```markdown +# CLI Module +::: hatch.cli_hatch +``` +``` + +**Required Update:** Update example to show new CLI package pattern. + +--- + +## Files NOT to Modify + +| Category | Files | Reason | +|----------|-------|--------| +| Historical Analysis | `__reports__/CLI-refactoring/00-04*.md` | Document pre-refactoring state | +| Design Documents | `__design__/cli-refactoring-*.md` | Document refactoring plan | +| Handover Documents | `__design__/handover-*.md` | Document session context | + +--- + +## Update Strategy + +### Handler Location Mapping + +| Handler/Function | Old Location | New Location | +|------------------|--------------|--------------| +| `main()` | `hatch.cli_hatch` | `hatch.cli.__main__` | +| `handle_mcp_configure()` | `hatch.cli_hatch` | `hatch.cli.cli_mcp` | +| `handle_mcp_*()` | `hatch.cli_hatch` | `hatch.cli.cli_mcp` | +| `handle_env_*()` | `hatch.cli_hatch` | `hatch.cli.cli_env` | +| `handle_package_*()` | `hatch.cli_hatch` | `hatch.cli.cli_package` | +| `handle_create()`, `handle_validate()` | `hatch.cli_hatch` | `hatch.cli.cli_system` | +| `parse_host_list()`, utilities | `hatch.cli_hatch` | `hatch.cli.cli_utils` | +| Argument parsing | `hatch.cli_hatch` | `hatch.cli.__main__` | + +### Backward Compatibility Note + +`hatch/cli_hatch.py` remains as a backward compatibility shim that re-exports all public symbols. External consumers can still import from `hatch.cli_hatch`, but new code should use `hatch.cli.*`. + +--- + +## Implementation Checklist + +- [x] Update `docs/articles/api/cli.md` - Expand API documentation +- [x] Update `docs/articles/users/CLIReference.md` - Fix intro paragraph +- [x] Update `docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md` - Fix CLI integration section +- [x] Update `docs/articles/devs/architecture/mcp_host_configuration.md` - Fix CLI reference +- [x] Update `docs/resources/diagrams/architecture.puml` - Update CLI component +- [x] Update `cracking-shells-playbook/instructions/documentation-api.instructions.md` - Update example + +--- + +## Risk Assessment + +| Risk | Likelihood | Impact | Mitigation | +|------|------------|--------|------------| +| Broken mkdocstrings generation | High | Medium | Test docs build after changes | +| Developer confusion from outdated guides | Medium | High | Prioritize implementation guide updates | +| Diagram regeneration issues | Low | Low | Verify PlantUML syntax | + diff --git a/__reports__/standards-retrospective/02-fresh_eye_review_v0.md b/__reports__/standards-retrospective/02-fresh_eye_review_v0.md new file mode 100644 index 0000000..be058a1 --- /dev/null +++ b/__reports__/standards-retrospective/02-fresh_eye_review_v0.md @@ -0,0 +1,82 @@ +# Fresh-Eye Review β€” Post-Implementation Gap Analysis (v0) + +Date: 2026-02-19 +Follows: `01-instructions_redesign_v3.md` implementation via `__roadmap__/instructions-redesign/` + +## Executive Summary + +After the instruction files were rewritten/edited per the v3 redesign, a fresh-eye review reveals **residual stale terminology** in 6 files that were NOT in the Β§11 affected list, **1 stale cross-reference** in a file that WAS edited, and **1 useful addition** (the `roadmap-execution.instructions.md`) that emerged during implementation but wasn't anticipated in the architecture report. A companion JSON schema (`roadmap-document-schema.json`) is proposed and delivered alongside this report. + +## Findings + +### F1: Stale "Phase N" Terminology in Edited Files + +These files were in the Β§11 scope and were edited, but retain stale Phase references: + +| File | Location | Stale Text | Suggested Fix | +|:-----|:---------|:-----------|:--------------| +| `reporting.instructions.md` | Β§2 "Default artifacts" | "Phase 1: Mermaid diagrams…" / "Phase 2: Risk-driven test matrix…" | Replace with "Architecture reports:" / "Test definition reports:" (drop phase numbering) | +| `reporting.instructions.md` | Β§"Specialized reporting guidance" | "Phase 1 architecture guidance" / "Phase 2 test definition reports" | "Architecture reporting guidance" / "Test definition reporting guidance" | +| `reporting.instructions.md` | Β§"Where reports go" | "Use `__design__/` for durable design/roadmaps." | "Use `__design__/` for durable architectural decisions." (roadmaps go in `__roadmap__/`, already stated in reporting-structure) | +| `reporting-architecture.instructions.md` | Title + front-matter + opening line | "Phase 1" in title, description, and body | "Stage 1" or simply "Architecture Reporting" | +| `reporting-structure.instructions.md` | Β§3 README convention | "Phase 1/2/3 etc." | "Stage 1/2/3 etc." or "Analysis/Roadmap/Execution" | + +**Severity**: Low β€” cosmetic inconsistency, but agents parsing these instructions may be confused by mixed terminology. + +### F2: Stale "Phase N" Terminology in Files Outside Β§11 Scope + +These files were NOT listed in Β§11 and were not touched during the campaign: + +| File | Location | Stale Text | Suggested Fix | +|:-----|:---------|:-----------|:--------------| +| `reporting-tests.instructions.md` | Title, front-matter, Β§body (6+ occurrences) | "Phase 2" throughout | "Stage 1" or "Test Definition Reporting" (tests are defined during Analysis, not a separate phase) | +| `reporting-templates.instructions.md` | Front-matter + section headers | "Phase 1" / "Phase 2" template headers | "Architecture Analysis" / "Test Definition" | +| `reporting-templates.instructions.md` | Β§Roadmap Recommendation | "create `__design__/_roadmap_vN.md`" | "create a roadmap directory tree under `__roadmap__//`" | +| `reporting-knowledge-transfer.instructions.md` | Β§"What not to do" | "link to Phase 1 artifacts" | "link to Stage 1 analysis artifacts" | +| `analytic-behavior.instructions.md` | Β§"Two-Phase Work Process" | "Phase 1: Analysis and Documentation" / "Phase 2: Implementation with Context Refresh" | This is a different "phase" concept (analysis vs implementation within a single session), not the old 7-phase model. **Ambiguous but arguably fine** β€” the two-phase work process here is about agent behavior, not the code-change workflow. Consider renaming to "Two-Step Work Process" or "Analysis-First Work Process" to avoid confusion. | +| `testing.instructions.md` | Β§2.3 | "Phase 2 report format" | "Test definition report format" | +| `testing.instructions.md` | Β§2.3 reference text | "Phase 2 in code change phases" | "Stage 1 (Analysis) in code change phases" | + +**Severity**: Medium for `reporting-tests.instructions.md` and `reporting-templates.instructions.md` (heavily used during Stage 1 work). Low for the others. + +### F3: Missing Cross-Reference in `code-change-phases.instructions.md` + +Stage 3 (Execution) describes the breadth-first algorithm but does NOT link to `roadmap-execution.instructions.md`, which contains the detailed operational manual (failure handling escalation ladder, subagent dispatch protocol, status update discipline, completion checklist). + +**Suggested fix**: Add a reference in Stage 3: +```markdown +For the detailed operational manual (failure handling, subagent dispatch, status updates), see [roadmap-execution.instructions.md](./roadmap-execution.instructions.md). +``` + +### F4: `roadmap-execution.instructions.md` β€” Unanticipated but Valuable + +This file was created during the campaign but was not listed in v3 Β§11. It fills a genuine gap: the v3 report describes WHAT the execution model is, but the execution manual describes HOW an agent should operationally navigate it (including the escalation ladder, subagent dispatch, and status update discipline). + +**Recommendation**: Acknowledge in the v3 report's Β§11 table as an addition, or simply note it in the campaign's amendment log. No action needed β€” the file is well-written and consistent with the model. + +### F5: Schema Companion Delivered + +A JSON Schema (`roadmap-document-schema.json`) has been created alongside this report. It formally defines the required and optional fields for: +- `README.md` (directory-level entry point) +- Leaf Task files +- Steps within leaf tasks +- Supporting types (status values, amendment log entries, progress entries, Mermaid node definitions) + +Location: `cracking-shells-playbook/instructions/roadmap-document-schema.json` + +--- + +## Prioritized Fix List + +| Priority | Finding | Files Affected | Effort | +|:---------|:--------|:---------------|:-------| +| 1 | F1: Stale terminology in edited files | 3 files | ~15 min (surgical text replacements) | +| 2 | F3: Missing cross-reference | 1 file | ~2 min | +| 3 | F2: Stale terminology in unscoped files | 5 files | ~45 min (more occurrences, some require judgment) | +| 4 | F4: Acknowledge execution manual | 1 file (v3 report or amendment log) | ~5 min | + +## Decision Required + +- **F1 + F3**: Straightforward fixes, recommend immediate application. +- **F2**: Larger scope. The `reporting-tests.instructions.md` and `reporting-templates.instructions.md` files have "Phase" deeply embedded. A dedicated task or amendment may be warranted. +- **F2 (analytic-behavior)**: The "Two-Phase Work Process" is arguably a different concept. Stakeholder judgment needed on whether to rename. diff --git a/cracking-shells-playbook b/cracking-shells-playbook index edb9a48..fd768bf 160000 --- a/cracking-shells-playbook +++ b/cracking-shells-playbook @@ -1 +1 @@ -Subproject commit edb9a48473b635a7204220b71af59f5e1f96ab89 +Subproject commit fd768bf6bc67c1ce916552521f781826acc65926 diff --git a/docs/_config.yml b/docs/_config.yml index 2d0fcb2..3f66bb5 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,2 +1,2 @@ theme: minima -repository: CrackingShells/Hatch \ No newline at end of file +repository: CrackingShells/Hatch diff --git a/docs/articles/api/cli.md b/docs/articles/api/cli.md deleted file mode 100644 index 9df6905..0000000 --- a/docs/articles/api/cli.md +++ /dev/null @@ -1,3 +0,0 @@ -# CLI Module - -::: hatch.cli_hatch diff --git a/docs/articles/api/cli/env.md b/docs/articles/api/cli/env.md new file mode 100644 index 0000000..5af9267 --- /dev/null +++ b/docs/articles/api/cli/env.md @@ -0,0 +1,58 @@ +# Environment Handlers + +The environment handlers module (`cli_env.py`) contains handlers for environment management commands. + +## Overview + +This module provides handlers for: + +- **Basic Environment Management**: Create, remove, list, use, current, show +- **Python Environment Management**: Initialize, info, remove, shell, add-hatch-mcp +- **Environment Listings**: List hosts, list servers (deployment views) + +## Handler Functions + +### Basic Environment Management +- `handle_env_create()`: Create new environments +- `handle_env_remove()`: Remove environments with confirmation +- `handle_env_list()`: List environments with table output +- `handle_env_use()`: Set current environment +- `handle_env_current()`: Show current environment +- `handle_env_show()`: Detailed hierarchical environment view + +### Python Environment Management +- `handle_env_python_init()`: Initialize Python virtual environment +- `handle_env_python_info()`: Show Python environment information +- `handle_env_python_remove()`: Remove Python virtual environment +- `handle_env_python_shell()`: Launch interactive Python shell +- `handle_env_python_add_hatch_mcp()`: Add hatch_mcp_server wrapper + +### Environment Listings +- `handle_env_list_hosts()`: Environment/host/server deployments +- `handle_env_list_servers()`: Environment/server/host deployments + +## Handler Signature + +All handlers follow the standard signature: + +```python +def handle_env_command(args: Namespace) -> int: + """Handle 'hatch env command' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - + + Returns: + Exit code (0 for success, 1 for error) + """ +``` + +## Module Reference + +::: hatch.cli.cli_env + options: + show_source: true + show_root_heading: true + heading_level: 2 diff --git a/docs/articles/api/cli/index.md b/docs/articles/api/cli/index.md new file mode 100644 index 0000000..ada5f7a --- /dev/null +++ b/docs/articles/api/cli/index.md @@ -0,0 +1,135 @@ +# CLI Package + +The CLI package provides the command-line interface for Hatch, organized into domain-specific handler modules following a handler-based architecture pattern. + +## Architecture Overview + +The CLI underwent a significant refactoring from a monolithic structure (`cli_hatch.py`) to a modular, handler-based architecture. This design emphasizes: + +- **Modularity**: Commands organized into focused handler modules +- **Consistency**: Unified output formatting across all commands +- **Extensibility**: Easy addition of new commands and features +- **Testability**: Clear separation of concerns for unit testing + +### Package Structure + +``` +hatch/cli/ +β”œβ”€β”€ __init__.py # Package exports and main() entry point +β”œβ”€β”€ __main__.py # Argument parsing and command routing +β”œβ”€β”€ cli_utils.py # Shared utilities and constants +β”œβ”€β”€ cli_mcp.py # MCP host configuration handlers +β”œβ”€β”€ cli_env.py # Environment management handlers +β”œβ”€β”€ cli_package.py # Package management handlers +└── cli_system.py # System commands (create, validate) +``` + +## Module Overview + +### Entry Point (`__main__.py`) +The routing layer that parses command-line arguments and delegates to appropriate handler modules. Initializes shared managers and attaches them to the args namespace for handler access. + +**Key Components**: +- `HatchArgumentParser`: Custom argument parser with formatted error messages +- Command routing functions +- Manager initialization + +### Utilities (`cli_utils.py`) +Shared infrastructure used across all handlers, including: + +- **Color System**: HCL color palette with true color support +- **ConsequenceType**: Dual-tense action labels for prompts and results +- **ResultReporter**: Unified rendering for mutation commands +- **TableFormatter**: Aligned table output for list commands +- **Error Formatting**: Structured validation and error messages + +### Handler Modules +Domain-specific command implementations: + +- **Environment Handlers** (`cli_env.py`): Environment lifecycle and Python environment operations +- **Package Handlers** (`cli_package.py`): Package installation, removal, and synchronization +- **MCP Handlers** (`cli_mcp.py`): MCP host configuration, discovery, and backup +- **System Handlers** (`cli_system.py`): System-level operations (package creation, validation) + +## Getting Started + +### Programmatic Usage + +```python +from hatch.cli import main, EXIT_SUCCESS, EXIT_ERROR + +# Run CLI programmatically +exit_code = main() + +# Or import specific handlers +from hatch.cli.cli_env import handle_env_create +from hatch.cli.cli_utils import ResultReporter, ConsequenceType +``` + +### Handler Signature Pattern + +All handlers follow a consistent signature: + +```python +def handle_command(args: Namespace) -> int: + """Handle 'hatch command' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - mcp_manager: MCPHostConfigurationManager instance (if needed) + - + + Returns: + Exit code (0 for success, 1 for error) + """ + # Implementation + return EXIT_SUCCESS +``` + +## Output Formatting + +The CLI uses a unified output formatting system: + +### Mutation Commands +Commands that modify state use `ResultReporter`: + +```python +reporter = ResultReporter("hatch env create", dry_run=False) +reporter.add(ConsequenceType.CREATE, "Environment 'dev'") +reporter.report_result() +``` + +### List Commands +Commands that display data use `TableFormatter`: + +```python +from hatch.cli.cli_utils import TableFormatter, ColumnDef + +columns = [ + ColumnDef(name="Name", width=20), + ColumnDef(name="Status", width=10), +] +formatter = TableFormatter(columns) +formatter.add_row(["my-env", "active"]) +print(formatter.render()) +``` + +## Backward Compatibility + +The old monolithic `hatch.cli_hatch` module has been refactored into the modular structure. For backward compatibility, imports from `hatch.cli_hatch` are still supported but deprecated: + +```python +# Old (deprecated, still works): +from hatch.cli_hatch import main, handle_mcp_configure + +# New (preferred): +from hatch.cli import main +from hatch.cli.cli_mcp import handle_mcp_configure +``` + +## Related Documentation + +- [CLI Architecture](../../devs/architecture/cli_architecture.md): Detailed architectural design and patterns +- [Adding CLI Commands](../../devs/implementation_guides/adding_cli_commands.md): Step-by-step implementation guide +- [CLI Reference](../../users/CLIReference.md): User-facing command documentation diff --git a/docs/articles/api/cli/main.md b/docs/articles/api/cli/main.md new file mode 100644 index 0000000..6427d08 --- /dev/null +++ b/docs/articles/api/cli/main.md @@ -0,0 +1,20 @@ +# Entry Point Module + +The entry point module (`__main__.py`) serves as the routing layer for the Hatch CLI, handling argument parsing and command delegation. + +## Overview + +This module provides: + +- Command-line argument parsing using `argparse` +- Custom `HatchArgumentParser` with formatted error messages +- Manager initialization (HatchEnvironmentManager, MCPHostConfigurationManager) +- Command routing to appropriate handler modules + +## Module Reference + +::: hatch.cli.__main__ + options: + show_source: true + show_root_heading: true + heading_level: 2 diff --git a/docs/articles/api/cli/mcp.md b/docs/articles/api/cli/mcp.md new file mode 100644 index 0000000..a0b824f --- /dev/null +++ b/docs/articles/api/cli/mcp.md @@ -0,0 +1,82 @@ +# MCP Handlers + +The MCP handlers module (`cli_mcp.py`) contains handlers for MCP host configuration commands. + +## Overview + +This module provides handlers for: + +- **Discovery**: Detect available MCP host platforms and servers +- **Listing**: Host-centric and server-centric views +- **Show Commands**: Detailed hierarchical views +- **Configuration**: Configure servers on hosts +- **Backup Management**: Restore, list, and clean backups +- **Removal**: Remove servers and hosts +- **Synchronization**: Sync configurations between environments and hosts + +## Supported Hosts + +- claude-desktop: Claude Desktop application +- claude-code: Claude Code extension +- cursor: Cursor IDE +- vscode: Visual Studio Code with Copilot +- kiro: Kiro IDE +- codex: OpenAI Codex +- lm-studio: LM Studio +- gemini: Google Gemini + +## Handler Functions + +### Discovery +- `handle_mcp_discover_hosts()`: Detect available MCP host platforms +- `handle_mcp_discover_servers()`: Find MCP servers in packages (deprecated) + +### Listing +- `handle_mcp_list_hosts()`: Host-centric server listing (shows all servers on hosts) +- `handle_mcp_list_servers()`: Server-centric host listing (shows all hosts for servers) + +### Show Commands +- `handle_mcp_show_hosts()`: Detailed hierarchical view of host configurations +- `handle_mcp_show_servers()`: Detailed hierarchical view of server configurations + +### Configuration +- `handle_mcp_configure()`: Configure MCP server on host with all host-specific arguments + +### Backup Management +- `handle_mcp_backup_restore()`: Restore configuration from backup +- `handle_mcp_backup_list()`: List available backups +- `handle_mcp_backup_clean()`: Clean old backups based on criteria + +### Removal +- `handle_mcp_remove_server()`: Remove server from hosts +- `handle_mcp_remove_host()`: Remove entire host configuration + +### Synchronization +- `handle_mcp_sync()`: Synchronize configurations between environments and hosts + +## Handler Signature + +All handlers follow the standard signature: + +```python +def handle_mcp_command(args: Namespace) -> int: + """Handle 'hatch mcp command' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - mcp_manager: MCPHostConfigurationManager instance + - + + Returns: + Exit code (0 for success, 1 for error) + """ +``` + +## Module Reference + +::: hatch.cli.cli_mcp + options: + show_source: true + show_root_heading: true + heading_level: 2 diff --git a/docs/articles/api/cli/package.md b/docs/articles/api/cli/package.md new file mode 100644 index 0000000..51c42d6 --- /dev/null +++ b/docs/articles/api/cli/package.md @@ -0,0 +1,51 @@ +# Package Handlers + +The package handlers module (`cli_package.py`) contains handlers for package management commands. + +## Overview + +This module provides handlers for: + +- **Package Installation**: Add packages to environments +- **Package Removal**: Remove packages with confirmation +- **Package Listing**: List packages (deprecated - use `env list`) +- **Package Synchronization**: Synchronize package MCP servers to hosts + +## Handler Functions + +### Package Management +- `handle_package_add()`: Add packages to environments with optional host configuration +- `handle_package_remove()`: Remove packages with confirmation +- `handle_package_list()`: List packages (deprecated - use `hatch env list`) +- `handle_package_sync()`: Synchronize package MCP servers to hosts + +### Internal Helpers +- `_get_package_names_with_dependencies()`: Get package name and dependencies +- `_configure_packages_on_hosts()`: Shared logic for configuring packages on hosts + +## Handler Signature + +All handlers follow the standard signature: + +```python +def handle_package_command(args: Namespace) -> int: + """Handle 'hatch package command' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - mcp_manager: MCPHostConfigurationManager instance + - + + Returns: + Exit code (0 for success, 1 for error) + """ +``` + +## Module Reference + +::: hatch.cli.cli_package + options: + show_source: true + show_root_heading: true + heading_level: 2 diff --git a/docs/articles/api/cli/system.md b/docs/articles/api/cli/system.md new file mode 100644 index 0000000..f77a870 --- /dev/null +++ b/docs/articles/api/cli/system.md @@ -0,0 +1,57 @@ +# System Handlers + +The system handlers module (`cli_system.py`) contains handlers for system-level commands that operate on packages outside of environments. + +## Overview + +This module provides handlers for: + +- **Package Creation**: Generate package templates from scratch +- **Package Validation**: Validate packages against the Hatch schema + +## Handler Functions + +### Package Creation +- `handle_create()`: Create a new package template with standard structure + +**Features**: +- Generates complete package template +- Creates pyproject.toml with Hatch metadata +- Sets up source directory structure +- Includes README and LICENSE files +- Provides basic MCP server implementation + +### Package Validation +- `handle_validate()`: Validate a package against the Hatch schema + +**Validation Checks**: +- pyproject.toml structure and required fields +- Hatch-specific metadata (mcp_server entry points) +- Package dependencies and version constraints +- Package structure compliance + +## Handler Signature + +All handlers follow the standard signature: + +```python +def handle_system_command(args: Namespace) -> int: + """Handle 'hatch command' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - + + Returns: + Exit code (0 for success, 1 for error) + """ +``` + +## Module Reference + +::: hatch.cli.cli_system + options: + show_source: true + show_root_heading: true + heading_level: 2 diff --git a/docs/articles/api/cli/utils.md b/docs/articles/api/cli/utils.md new file mode 100644 index 0000000..9815eec --- /dev/null +++ b/docs/articles/api/cli/utils.md @@ -0,0 +1,54 @@ +# Utilities Module + +The utilities module (`cli_utils.py`) provides shared infrastructure used across all CLI handlers. + +## Overview + +This module contains: + +- **Color System**: HCL color palette with true color support and 16-color fallback +- **ConsequenceType**: Dual-tense action labels (prompt/result) with semantic colors +- **ResultReporter**: Unified rendering system for mutation commands +- **TableFormatter**: Aligned table output for list commands +- **Error Formatting**: Structured validation and error messages +- **Parsing Utilities**: Functions for parsing command-line arguments + +## Key Components + +### Color System +- `Color` enum: HCL color palette with semantic mapping +- `_colors_enabled()`: TTY detection and NO_COLOR support +- `_supports_truecolor()`: True color capability detection +- `highlight()`: Entity name highlighting for show commands + +### ConsequenceType System +- Dual-tense labels (present for prompts, past for results) +- Semantic color mapping (green=constructive, red=destructive, etc.) +- Categories: Constructive, Recovery, Destructive, Modification, Transfer, Informational, No-op + +### Output Formatting +- `ResultReporter`: Tracks consequences and renders with tense-aware colors +- `TableFormatter`: Renders aligned tables with auto-width support +- `Consequence`: Data model for nested consequences + +### Error Handling +- `ValidationError`: Structured validation errors with field and suggestion +- `format_validation_error()`: Formatted error output +- `format_info()`: Info messages +- `format_warning()`: Warning messages + +### Utilities +- `request_confirmation()`: User confirmation with auto-approve support +- `parse_env_vars()`: Parse KEY=VALUE environment variables +- `parse_header()`: Parse KEY=VALUE HTTP headers +- `parse_input()`: Parse VS Code input variable definitions +- `parse_host_list()`: Parse comma-separated hosts or 'all' +- `get_package_mcp_server_config()`: Extract MCP config from package metadata + +## Module Reference + +::: hatch.cli.cli_utils + options: + show_source: true + show_root_heading: true + heading_level: 2 diff --git a/docs/articles/api/index.md b/docs/articles/api/index.md index 31bb28a..04efadf 100644 --- a/docs/articles/api/index.md +++ b/docs/articles/api/index.md @@ -4,21 +4,61 @@ Welcome to the Hatch API Reference documentation. This section provides detailed ## Overview -Hatch is a comprehensive package manager for the Cracking Shells ecosystem. The API is organized into several key modules: +Hatch is a comprehensive package manager for the Cracking Shells ecosystem. The API is organized into several key areas: -- **Core Modules**: Main functionality for CLI, environment management, package loading, etc. +- **CLI Package**: Modular command-line interface with handler-based architecture +- **Core Modules**: Environment management, package loading, and registry operations - **Installers**: Various installation backends and orchestration components ## Getting Started -To use Hatch programmatically, you can import the main modules: +To use Hatch programmatically, import from the appropriate modules: ```python -from hatch import cli_hatch -from hatch.environment_manager import EnvironmentManager +# CLI entry point +from hatch.cli import main, EXIT_SUCCESS, EXIT_ERROR + +# Core managers +from hatch.environment_manager import HatchEnvironmentManager from hatch.package_loader import PackageLoader + +# CLI handlers (for programmatic command execution) +from hatch.cli.cli_env import handle_env_create +from hatch.cli.cli_utils import ResultReporter, ConsequenceType ``` +## Module Organization + +### CLI Package +The command-line interface is organized into specialized handler modules: + +- **Entry Point** (`__main__.py`): Argument parsing and command routing +- **Utilities** (`cli_utils.py`): Shared formatting and utility functions +- **Environment Handlers** (`cli_env.py`): Environment lifecycle operations +- **Package Handlers** (`cli_package.py`): Package installation and management +- **MCP Handlers** (`cli_mcp.py`): MCP host configuration and backup +- **System Handlers** (`cli_system.py`): Package creation and validation + +### Core Modules +Essential functionality for package and environment management: + +- **Environment Manager**: Environment lifecycle and state management +- **Package Loader**: Package loading and validation +- **Python Environment Manager**: Python virtual environment operations +- **Registry Explorer**: Package discovery and registry interaction +- **Template Generator**: Package template creation + +### Installers +Specialized installation backends for different dependency types: + +- **Base Installer**: Common installer interface +- **Docker Installer**: Docker image dependencies +- **Hatch Installer**: Hatch package dependencies +- **Python Installer**: Python package installation via pip +- **System Installer**: System package installation +- **Installation Context**: Installation state management +- **Dependency Orchestrator**: Multi-type dependency coordination + ## Module Index Browse the detailed API documentation for each module using the navigation on the left. diff --git a/docs/articles/appendices/state_and_data_models.md b/docs/articles/appendices/state_and_data_models.md index 1a708f7..a3f15a1 100644 --- a/docs/articles/appendices/state_and_data_models.md +++ b/docs/articles/appendices/state_and_data_models.md @@ -12,7 +12,7 @@ The complete package metadata schema is defined in `Hatch-Schemas/package/v1.2.0 { "package_schema_version": "1.2.0", "name": "package_name", - "version": "1.0.0", + "version": "1.0.0", "entry_point": "hatch_mcp_server_entry.py", "description": "Package description", "tags": ["tag1", "tag2"], diff --git a/docs/articles/devs/architecture/cli_architecture.md b/docs/articles/devs/architecture/cli_architecture.md new file mode 100644 index 0000000..98b3bf9 --- /dev/null +++ b/docs/articles/devs/architecture/cli_architecture.md @@ -0,0 +1,295 @@ +# CLI Architecture + +This article documents the architectural design of Hatch's command-line interface, which underwent a significant refactoring from a monolithic structure to a modular, handler-based architecture. + +## Overview + +The Hatch CLI provides a comprehensive interface for managing MCP server packages, environments, and host configurations. The architecture emphasizes: + +- **Modularity**: Commands organized into focused handler modules +- **Consistency**: Unified output formatting across all commands +- **Extensibility**: Easy addition of new commands and features +- **Testability**: Clear separation of concerns for unit testing + +## Architecture Components + +### Entry Point (`hatch/cli/__main__.py`) + +The entry point module serves as the routing layer: + +1. **Argument Parsing**: Uses `argparse` with custom `HatchArgumentParser` for formatted error messages +2. **Manager Initialization**: Creates shared `HatchEnvironmentManager` and `MCPHostConfigurationManager` instances +3. **Manager Attachment**: Attaches managers to the `args` namespace for handler access +4. **Command Routing**: Routes parsed commands to appropriate handler modules + +**Key Pattern**: +```python +# Managers initialized once and shared across handlers +env_manager = HatchEnvironmentManager(...) +mcp_manager = MCPHostConfigurationManager() + +# Attached to args for handler access +args.env_manager = env_manager +args.mcp_manager = mcp_manager + +# Routed to handlers +return _route_env_command(args) +``` + +### Handler Modules + +Commands are organized into four domain-specific handler modules: + +#### `cli_env.py` - Environment Management +Handles environment lifecycle and Python environment operations: +- `handle_env_create()`: Create new environments +- `handle_env_remove()`: Remove environments with confirmation +- `handle_env_list()`: List environments with table output +- `handle_env_use()`: Set current environment +- `handle_env_current()`: Show current environment +- `handle_env_show()`: Detailed hierarchical environment view +- `handle_env_list_hosts()`: Environment/host/server deployments +- `handle_env_list_servers()`: Environment/server/host deployments +- `handle_env_python_*()`: Python environment operations + +#### `cli_package.py` - Package Management +Handles package installation and synchronization: +- `handle_package_add()`: Add packages to environments +- `handle_package_remove()`: Remove packages with confirmation +- `handle_package_list()`: List packages (deprecated - use `env list`) +- `handle_package_sync()`: Synchronize package MCP servers to hosts +- `_configure_packages_on_hosts()`: Shared configuration logic + +#### `cli_mcp.py` - MCP Host Configuration +Handles MCP host platform configuration and backup: +- `handle_mcp_discover_hosts()`: Detect available host platforms +- `handle_mcp_list_hosts()`: Host-centric server listing +- `handle_mcp_list_servers()`: Server-centric host listing +- `handle_mcp_show_hosts()`: Detailed host configurations +- `handle_mcp_show_servers()`: Detailed server configurations +- `handle_mcp_configure()`: Configure servers on hosts +- `handle_mcp_backup_*()`: Backup management operations +- `handle_mcp_remove_*()`: Server and host removal +- `handle_mcp_sync()`: Synchronize configurations + +#### `cli_system.py` - System Operations +Handles package creation and validation: +- `handle_create()`: Generate package templates +- `handle_validate()`: Validate package structure + +### Shared Utilities (`cli_utils.py`) + +The utilities module provides infrastructure used across all handlers: + +#### Color System +- **`Color` enum**: HCL color palette with true color support and 16-color fallback +- **Dual-tense colors**: Dim colors for prompts (present tense), bright colors for results (past tense) +- **Semantic mapping**: Colors mapped to action categories (green=constructive, red=destructive, etc.) +- **`_colors_enabled()`**: Respects `NO_COLOR` environment variable and TTY detection + +#### ConsequenceType System +- **`ConsequenceType` enum**: Action types with dual-tense labels +- **Prompt labels**: Present tense for confirmation (e.g., "CREATE") +- **Result labels**: Past tense for execution (e.g., "CREATED") +- **Color association**: Each type has prompt and result colors +- **Categories**: Constructive, Recovery, Destructive, Modification, Transfer, Informational, No-op + +#### ResultReporter +Unified rendering system for all CLI output: + +**Key Features**: +- Tracks consequences (actions to be performed) +- Generates confirmation prompts (present tense, dim colors) +- Reports execution results (past tense, bright colors) +- Supports nested consequences (resource β†’ field level) +- Handles dry-run mode with suffix labels +- Provides error and partial success reporting + +**Usage Pattern**: +```python +reporter = ResultReporter("hatch env create", dry_run=False) +reporter.add(ConsequenceType.CREATE, "Environment 'dev'") +reporter.add(ConsequenceType.CREATE, "Python environment (3.11)") + +# Show prompt and get confirmation +prompt = reporter.report_prompt() +if prompt: + print(prompt) +if not request_confirmation("Proceed?"): + return EXIT_SUCCESS + +# Execute operation... + +# Report results +reporter.report_result() +``` + +#### TableFormatter +Aligned table output for list commands: + +**Features**: +- Fixed and auto-calculated column widths +- Left/right/center alignment support +- Automatic truncation with ellipsis +- Consistent header and separator rendering + +**Usage Pattern**: +```python +columns = [ + ColumnDef(name="Name", width=20), + ColumnDef(name="Status", width=10), + ColumnDef(name="Count", width="auto", align="right"), +] +formatter = TableFormatter(columns) +formatter.add_row(["my-env", "active", "5"]) +print(formatter.render()) +``` + +#### Error Formatting +- **`ValidationError`**: Structured validation errors with field and suggestion +- **`format_validation_error()`**: Formatted error output with color +- **`format_info()`**: Info messages with [INFO] prefix +- **`format_warning()`**: Warning messages with [WARNING] prefix + +#### Parsing Utilities +- **`parse_env_vars()`**: Parse KEY=VALUE environment variables +- **`parse_header()`**: Parse KEY=VALUE HTTP headers +- **`parse_input()`**: Parse VS Code input variable definitions +- **`parse_host_list()`**: Parse comma-separated hosts or 'all' +- **`get_package_mcp_server_config()`**: Extract MCP config from package metadata + +## Handler Signature Convention + +All handlers follow a consistent signature: + +```python +def handle_command(args: Namespace) -> int: + """Handle 'hatch command' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - mcp_manager: MCPHostConfigurationManager instance (if needed) + - + + Returns: + Exit code (0 for success, 1 for error) + """ +``` + +**Key Invariants**: +- Managers accessed via `args.env_manager` and `args.mcp_manager` +- Return `EXIT_SUCCESS` (0) on success, `EXIT_ERROR` (1) on failure +- Use `ResultReporter` for unified output +- Handle dry-run mode consistently +- Request confirmation for destructive operations + +## Output Formatting Standards + +### Mutation Commands +Commands that modify state follow this pattern: + +1. **Build consequences**: Add all actions to `ResultReporter` +2. **Show prompt**: Display present-tense preview with dim colors +3. **Request confirmation**: Use `request_confirmation()` unless auto-approved +4. **Execute**: Perform the actual operations +5. **Report results**: Display past-tense results with bright colors + +### List Commands +Commands that display data use `TableFormatter`: + +1. **Define columns**: Specify widths and alignment +2. **Add rows**: Populate with data +3. **Render**: Print formatted table with headers and separator + +### Show Commands +Commands that display detailed views use hierarchical output: + +1. **Header**: Entity name with `highlight()` for emphasis +2. **Metadata**: Key-value pairs with indentation +3. **Sections**: Grouped related information +4. **Separators**: Use `═` for visual separation between entities + +## Exit Code Standards + +- **`EXIT_SUCCESS` (0)**: Operation completed successfully +- **`EXIT_ERROR` (1)**: Operation failed or validation error +- **Partial success**: Return `EXIT_ERROR` but use `report_partial_success()` + +## Design Principles + +### Separation of Concerns +- **Routing**: `__main__.py` handles argument parsing and routing only +- **Business logic**: Handler modules implement command logic +- **Presentation**: `cli_utils.py` provides formatting infrastructure +- **Domain logic**: Managers (`HatchEnvironmentManager`, `MCPHostConfigurationManager`) handle state + +### DRY (Don't Repeat Yourself) +- Shared utilities in `cli_utils.py` eliminate duplication +- `ResultReporter` provides consistent output across all commands +- `TableFormatter` standardizes list output +- Parsing utilities handle common argument formats + +### Consistency +- All handlers follow the same signature pattern +- All mutation commands use `ResultReporter` +- All list commands use `TableFormatter` +- All errors use structured formatting + +### Testability +- Handlers are pure functions (input β†’ output) +- Managers injected via `args` namespace (dependency injection) +- Clear separation between CLI and business logic +- Utilities are independently testable + +## Command Organization + +### Namespace Structure +``` +hatch +β”œβ”€β”€ create # System: Package template creation +β”œβ”€β”€ validate # System: Package validation +β”œβ”€β”€ env # Environment management +β”‚ β”œβ”€β”€ create +β”‚ β”œβ”€β”€ remove +β”‚ β”œβ”€β”€ list [hosts|servers] +β”‚ β”œβ”€β”€ use +β”‚ β”œβ”€β”€ current +β”‚ β”œβ”€β”€ show +β”‚ └── python +β”‚ β”œβ”€β”€ init +β”‚ β”œβ”€β”€ info +β”‚ β”œβ”€β”€ remove +β”‚ β”œβ”€β”€ shell +β”‚ └── add-hatch-mcp +β”œβ”€β”€ package # Package management +β”‚ β”œβ”€β”€ add +β”‚ β”œβ”€β”€ remove +β”‚ β”œβ”€β”€ list (deprecated) +β”‚ └── sync +└── mcp # MCP host configuration + β”œβ”€β”€ discover + β”‚ β”œβ”€β”€ hosts + β”‚ └── servers + β”œβ”€β”€ list + β”‚ β”œβ”€β”€ hosts + β”‚ └── servers + β”œβ”€β”€ show + β”‚ β”œβ”€β”€ hosts + β”‚ └── servers + β”œβ”€β”€ configure + β”œβ”€β”€ remove + β”‚ β”œβ”€β”€ server + β”‚ └── host + β”œβ”€β”€ sync + └── backup + β”œβ”€β”€ restore + β”œβ”€β”€ list + └── clean +``` + +## Related Documentation + +- [Adding CLI Commands](../implementation_guides/adding_cli_commands.md): Step-by-step guide for adding new commands +- [Component Architecture](./component_architecture.md): Overall system architecture +- [CLI Reference](../../users/CLIReference.md): User-facing command documentation diff --git a/docs/articles/devs/architecture/component_architecture.md b/docs/articles/devs/architecture/component_architecture.md index 722a1d5..bd727b9 100644 --- a/docs/articles/devs/architecture/component_architecture.md +++ b/docs/articles/devs/architecture/component_architecture.md @@ -108,6 +108,71 @@ This article is about: - Multiple registry source support - Package relationship analysis +### CLI Components + +#### Entry Point (`hatch/cli/__main__.py`) + +**Responsibilities:** + +- Command-line argument parsing and validation +- Manager initialization and dependency injection +- Command routing to appropriate handler modules +- Top-level error handling and exit code management + +**Key Features:** + +- Custom `HatchArgumentParser` with formatted error messages +- Shared manager instances (HatchEnvironmentManager, MCPHostConfigurationManager) +- Modular command routing to handler modules +- Consistent argument structure across all commands + +#### Handler Modules (`hatch/cli/cli_*.py`) + +**Responsibilities:** + +- Domain-specific command implementation +- Business logic orchestration using managers +- User interaction and confirmation prompts +- Output formatting using shared utilities + +**Handler Modules:** + +- **cli_env.py** - Environment lifecycle and Python environment operations +- **cli_package.py** - Package installation, removal, and synchronization +- **cli_mcp.py** - MCP host configuration, discovery, and backup +- **cli_system.py** - System-level operations (package creation, validation) + +**Key Features:** + +- Consistent handler signature: `(args: Namespace) -> int` +- Unified output formatting via ResultReporter +- Dry-run mode support for mutation commands +- Confirmation prompts for destructive operations + +#### Shared Utilities (`hatch/cli/cli_utils.py`) + +**Responsibilities:** + +- Unified output formatting infrastructure +- Color system with true color support and TTY detection +- Table formatting for list commands +- Error formatting and validation utilities + +**Key Components:** + +- **Color System** - HCL color palette with semantic mapping +- **ConsequenceType** - Dual-tense action labels (prompt/result) +- **ResultReporter** - Unified rendering for mutation commands +- **TableFormatter** - Aligned table output for list commands +- **Error Formatting** - Structured validation and error messages + +**Key Features:** + +- Respects NO_COLOR environment variable +- True color (24-bit) with 16-color fallback +- Consistent output across all commands +- Nested consequence support (resource β†’ field level) + ### Installation System Components #### DependencyInstallerOrchestrator (`hatch/installers/dependency_installation_orchestrator.py`) @@ -157,6 +222,18 @@ This article is about: ## Component Data Flow +### CLI Command Flow + +`User Input β†’ __main__.py (Argument Parsing) β†’ Handler Module β†’ Manager(s) β†’ Business Logic β†’ ResultReporter β†’ User Output` + +1. User executes CLI command with arguments +2. `__main__.py` parses arguments using argparse +3. Managers (HatchEnvironmentManager, MCPHostConfigurationManager) are initialized +4. Command is routed to appropriate handler module +5. Handler orchestrates business logic using manager methods +6. ResultReporter formats output with consistent styling +7. Exit code returned to shell + ### Environment Creation Flow `CLI Command β†’ HatchEnvironmentManager β†’ PythonEnvironmentManager β†’ Environment Metadata` @@ -287,5 +364,6 @@ This article is about: ## Related Documentation - [System Overview](./system_overview.md) - High-level architecture introduction +- [CLI Architecture](./cli_architecture.md) - Detailed CLI design and patterns - [Implementation Guides](../implementation_guides/index.md) - Technical implementation guidance for specific components - [Development Processes](../development_processes/index.md) - Development workflow and testing standards diff --git a/docs/articles/devs/architecture/index.md b/docs/articles/devs/architecture/index.md index 516fbbd..2e5c241 100644 --- a/docs/articles/devs/architecture/index.md +++ b/docs/articles/devs/architecture/index.md @@ -12,6 +12,7 @@ Hatch is a sophisticated package management system designed for the CrackingShel - **[System Overview](./system_overview.md)** - High-level introduction to Hatch's architecture and core concepts - **[Component Architecture](./component_architecture.md)** - Detailed breakdown of major system components and their relationships +- **[CLI Architecture](./cli_architecture.md)** - Command-line interface design, patterns, and output formatting ### Design Patterns diff --git a/docs/articles/devs/architecture/mcp_host_configuration.md b/docs/articles/devs/architecture/mcp_host_configuration.md index 09191d8..79cfc4b 100644 --- a/docs/articles/devs/architecture/mcp_host_configuration.md +++ b/docs/articles/devs/architecture/mcp_host_configuration.md @@ -1,169 +1,281 @@ # MCP Host Configuration Architecture -This article is about: +This article covers: -- Architecture and design patterns for MCP host configuration management -- Decorator-based strategy registration system +- Unified Adapter Architecture for MCP host configuration +- Adapter pattern for host-specific validation and serialization +- Unified data model (`MCPServerConfig`) - Extension points for adding new host platforms - Integration with backup and environment systems ## Overview -The MCP host configuration system provides centralized management of Model Context Protocol server configurations across multiple host platforms (Claude Desktop, VS Code, Cursor, Kiro, etc.). It uses a decorator-based architecture with inheritance patterns for clean code organization and easy extension. +The MCP host configuration system manages Model Context Protocol server configurations across multiple host platforms (Claude Desktop, VS Code, Cursor, Gemini, Kiro, Codex, LM Studio). It uses the **Unified Adapter Architecture**: a single data model with host-specific adapters for validation and serialization. > **Adding a new host?** See the [Implementation Guide](../implementation_guides/mcp_host_configuration_extension.md) for step-by-step instructions. ## Core Architecture -### Strategy Pattern with Decorator Registration +### Unified Adapter Pattern -The system uses the Strategy pattern combined with automatic registration via decorators: +The architecture separates concerns into three layers: -```python -@register_host_strategy(MCPHostType.CLAUDE_DESKTOP) -class ClaudeDesktopHostStrategy(ClaudeHostStrategy): - def get_config_path(self) -> Optional[Path]: - return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json" +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CLI Layer β”‚ +β”‚ Creates MCPServerConfig with all user-provided fields β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Adapter Layer β”‚ +β”‚ Validates + serializes to host-specific format β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Claude β”‚ β”‚ VSCode β”‚ β”‚ Gemini β”‚ β”‚ Kiro β”‚ ... β”‚ +β”‚ β”‚ Adapter β”‚ β”‚ Adapter β”‚ β”‚ Adapter β”‚ β”‚ Adapter β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Strategy Layer β”‚ +β”‚ Handles file I/O (read/write configuration files) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` **Benefits:** -- Automatic strategy discovery on module import -- No manual registry maintenance -- Clear separation of host-specific logic -- Easy addition of new host platforms - -### Inheritance Hierarchy -Host strategies are organized into families for code reuse: +- Single unified data model accepts all fields +- Adapters declaratively define supported fields per host +- No inheritance hierarchies or model conversion methods +- Easy addition of new hosts (3 steps instead of 10) -#### Claude Family -- **Base**: `ClaudeHostStrategy` -- **Shared behavior**: Absolute path validation, Anthropic-specific configuration handling -- **Implementations**: Claude Desktop, Claude Code +### Unified Data Model -#### Cursor Family -- **Base**: `CursorBasedHostStrategy` -- **Shared behavior**: Flexible path handling, common configuration format -- **Implementations**: Cursor, LM Studio +`MCPServerConfig` contains ALL possible fields from ALL hosts: -#### Independent Strategies -- **VSCode**: User-wide configuration (`~/.config/Code/User/mcp.json`), uses `servers` key -- **Gemini**: Official configuration path (`~/.gemini/settings.json`) -- **Kiro**: User-level configuration (`~/.kiro/settings/mcp.json`), full backup manager integration +```python +class MCPServerConfig(BaseModel): + """Unified model containing ALL possible fields.""" + model_config = ConfigDict(extra="allow") -### Consolidated Data Model + # Hatch metadata (never serialized) + name: Optional[str] = None -The `MCPServerConfig` model supports both local and remote server configurations: + # Transport fields + command: Optional[str] = None # stdio transport + url: Optional[str] = None # sse transport + httpUrl: Optional[str] = None # http transport (Gemini) -```python -class MCPServerConfig(BaseModel): - # Local server (command-based) - command: Optional[str] = None + # Universal fields (all hosts) args: Optional[List[str]] = None env: Optional[Dict[str, str]] = None - - # Remote server (URL-based) - url: Optional[str] = None headers: Optional[Dict[str, str]] = None + type: Optional[Literal["stdio", "sse", "http"]] = None + + # Host-specific fields + envFile: Optional[str] = None # VSCode/Cursor + disabled: Optional[bool] = None # Kiro + trust: Optional[bool] = None # Gemini + # ... additional fields per host ``` -**Cross-field validation** ensures either command OR url is provided, not both. +**Design principles:** + +- `extra="allow"` for forward compatibility with unknown fields +- Adapters handle validation (not the model) +- `name` field is Hatch metadata (defined in `EXCLUDED_ALWAYS`): + - Never serialized to host configuration files + - Never reported in CLI field operations + - Available as payload context within the unified model ## Key Components -### MCPHostRegistry +### AdapterRegistry -Central registry managing strategy instances: +Central registry mapping host names to adapter instances: -- **Singleton pattern**: One instance per strategy type -- **Automatic registration**: Triggered by decorator usage -- **Family organization**: Groups related strategies -- **Host detection**: Identifies available platforms +```python +from hatch.mcp_host_config.adapters import get_adapter, AdapterRegistry + +# Get adapter for a specific host +adapter = get_adapter("claude-desktop") -### MCPHostConfigurationManager +# Or use registry directly +registry = AdapterRegistry() +adapter = registry.get_adapter("gemini") +supported = registry.get_supported_hosts() # List all hosts +``` -Core configuration operations: +**Supported hosts:** -- **Server configuration**: Add/remove servers from host configurations -- **Environment synchronization**: Sync environment data to multiple hosts -- **Backup integration**: Atomic operations with rollback capability -- **Error handling**: Comprehensive result reporting +- `claude-desktop`, `claude-code` +- `vscode`, `cursor`, `lmstudio` +- `gemini`, `kiro`, `codex` -### Host Strategy Interface +### BaseAdapter Protocol -All strategies implement the `MCPHostStrategy` abstract base class: +All adapters implement this interface: ```python -class MCPHostStrategy(ABC): +class BaseAdapter(ABC): + @property + @abstractmethod + def host_name(self) -> str: + """Return host identifier (e.g., 'claude-desktop').""" + ... + @abstractmethod - def get_config_path(self) -> Optional[Path]: - """Get configuration file path for this host.""" - + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields this host accepts.""" + ... + @abstractmethod - def validate_server_config(self, server_config: MCPServerConfig) -> bool: - """Validate server configuration for this host.""" - + def validate(self, config: MCPServerConfig) -> None: + """DEPRECATED (v0.9.0): Use validate_filtered() instead.""" + ... + @abstractmethod - def read_configuration(self) -> HostConfiguration: - """Read current host configuration.""" - + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate ONLY fields that survived filtering.""" + ... + + def apply_transformations(self, filtered: Dict[str, Any]) -> Dict[str, Any]: + """Apply host-specific field name/value transformations (default: no-op).""" + return filtered + @abstractmethod - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write configuration to host.""" + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Convert config to host's expected format.""" + ... +``` + +**Serialization pattern (validate-after-filter):** + +``` +filter_fields(config) β†’ validate_filtered(filtered) β†’ apply_transformations(filtered) β†’ return +``` + +This pattern ensures validation only checks fields the host actually supports, +preventing false rejections during cross-host sync operations. + +### Field Constants + +Field support is defined in `fields.py`: + +```python +# Universal fields (all hosts) +UNIVERSAL_FIELDS = frozenset({"command", "args", "env", "url", "headers"}) + +# Host-specific field sets +CLAUDE_FIELDS = UNIVERSAL_FIELDS | frozenset({"type"}) +VSCODE_FIELDS = CLAUDE_FIELDS | frozenset({"envFile", "inputs"}) +GEMINI_FIELDS = UNIVERSAL_FIELDS | frozenset({"httpUrl", "timeout", "trust", ...}) +KIRO_FIELDS = UNIVERSAL_FIELDS | frozenset({"disabled", "autoApprove", ...}) + +# Metadata fields (never serialized or reported) +EXCLUDED_ALWAYS = frozenset({"name"}) +``` + +### Reporting System + +The reporting system (`reporting.py`) provides user-friendly feedback for MCP configuration operations. It respects adapter exclusion semantics to ensure consistency between what's reported and what's actually written to host configuration files. + +**Key components:** + +- `FieldOperation`: Represents a single field-level change (UPDATED, UNCHANGED, or UNSUPPORTED) +- `ConversionReport`: Complete report for a configuration operation +- `generate_conversion_report()`: Analyzes configuration against target host's adapter +- `display_report()`: Displays formatted report to console + +**Metadata field handling:** + +Fields in `EXCLUDED_ALWAYS` (like `name`) are completely omitted from field operation reports: + +```python +# Get excluded fields from adapter +excluded_fields = adapter.get_excluded_fields() + +for field_name, new_value in set_fields.items(): + # Skip metadata fields - they should never appear in reports + if field_name in excluded_fields: + continue + # ... process other fields ``` +This ensures that: +- Internal metadata fields never appear as UPDATED, UNCHANGED, or UNSUPPORTED +- Server name still appears in the report header for context +- Reporting behavior matches serialization behavior (both use `get_excluded_fields()`) + +## Field Support Matrix + +| Field | Claude | VSCode | Cursor | Gemini | Kiro | Codex | +|-------|--------|--------|--------|--------|------|-------| +| command, args, env | βœ“ | βœ“ | βœ“ | βœ“ | βœ“ | βœ“ | +| url, headers | βœ“ | βœ“ | βœ“ | βœ“ | βœ“ | βœ“ | +| type | βœ“ | βœ“ | βœ“ | - | - | - | +| envFile | - | βœ“ | βœ“ | - | - | - | +| inputs | - | βœ“ | - | - | - | - | +| httpUrl | - | - | - | βœ“ | - | - | +| trust, timeout | - | - | - | βœ“ | - | - | +| disabled, autoApprove | - | - | - | - | βœ“ | - | +| enabled, enabled_tools | - | - | - | - | - | βœ“ | + ## Integration Points -Every host strategy must integrate with these systems. Missing any integration point will result in incomplete functionality. +### Adapter Integration + +Every adapter integrates with the validation and serialization system: -### Backup System Integration (Required) +```python +from hatch.mcp_host_config.adapters import get_adapter +from hatch.mcp_host_config import MCPServerConfig + +# Create unified config +config = MCPServerConfig( + name="my-server", + command="python", + args=["server.py"], + env={"DEBUG": "true"}, +) + +# Serialize for specific host (filter β†’ validate β†’ transform) +adapter = get_adapter("claude-desktop") +data = adapter.serialize(config) +# Result: {"command": "python", "args": ["server.py"], "env": {"DEBUG": "true"}} + +# Cross-host sync: serialize for Codex (applies field mappings) +codex = get_adapter("codex") +codex_data = codex.serialize(config) +# Result: {"command": "python", "arguments": ["server.py"], "env": {"DEBUG": "true"}} +# Note: 'args' mapped to 'arguments', 'type' filtered out +``` -All configuration write operations **must** integrate with the backup system via `MCPHostConfigBackupManager` and `AtomicFileOperations`: +### Backup System Integration + +Strategy classes integrate with the backup system via `MCPHostConfigBackupManager`: ```python -from .backup import MCPHostConfigBackupManager, AtomicFileOperations +from hatch.mcp_host_config.backup import MCPHostConfigBackupManager, AtomicFileOperations def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - # ... prepare data ... backup_manager = MCPHostConfigBackupManager() atomic_ops = AtomicFileOperations() atomic_ops.atomic_write_with_backup( file_path=config_path, data=existing_data, backup_manager=backup_manager, - hostname="your-host", # Must match MCPHostType value + hostname="your-host", skip_backup=no_backup ) ``` -**Key requirements:** -- **Atomic operations**: Configuration changes are backed up before modification -- **Rollback capability**: Failed operations can be reverted automatically -- **Hostname identification**: Each host uses its `MCPHostType` value for backup tracking -- **Timestamped retention**: Backup files include timestamps for tracking - -### Model Registry Integration (Required for host-specific fields) - -If your host has unique configuration fields (like Kiro's `disabled`, `autoApprove`, `disabledTools`): - -1. Create host-specific model class in `models.py` -2. Register in `HOST_MODEL_REGISTRY` -3. Extend `MCPServerConfigOmni` with new fields -4. Implement `from_omni()` conversion method - -### CLI Integration (Required for host-specific arguments) - -If your host has unique CLI arguments: - -1. Extend `handle_mcp_configure()` function signature in `cli_hatch.py` -2. Add argument parser entries for new flags -3. Update omni model population logic - ### Environment Manager Integration -The system integrates with environment management through corrected data structures: +The system integrates with environment management: -- **Single-server-per-package constraint**: Realistic model reflecting actual usage +- **Single-server-per-package constraint**: One MCP server per installed package - **Multi-host configuration**: One server can be configured across multiple hosts - **Synchronization support**: Environment data can be synced to available hosts @@ -171,75 +283,76 @@ The system integrates with environment management through corrected data structu ### Adding New Host Platforms -To add support for a new host platform, complete these integration points: +To add a new host, complete these steps: -| Integration Point | Required? | Files to Modify | -|-------------------|-----------|-----------------| -| Host type enum | Always | `models.py` | -| Strategy class | Always | `strategies.py` | -| Backup integration | Always | `strategies.py` (in `write_configuration`) | -| Host-specific model | If unique fields | `models.py`, `HOST_MODEL_REGISTRY` | -| CLI arguments | If unique fields | `cli_hatch.py` | -| Test infrastructure | Always | `tests/` | +| Step | Files to Modify | +|------|-----------------| +| 1. Add host type enum | `models.py` (MCPHostType) | +| 2. Create adapter class | `adapters/your_host.py` + `adapters/__init__.py` | +| 3. Create strategy class | `strategies.py` | +| 4. Add tests | `tests/unit/mcp/`, `tests/integration/mcp/` | -**Minimal implementation** (standard host, no unique fields): +**Minimal adapter implementation:** ```python -@register_host_strategy(MCPHostType.NEW_HOST) -class NewHostStrategy(ClaudeHostStrategy): # Inherit backup integration - def get_config_path(self) -> Optional[Path]: - return Path.home() / ".new_host" / "config.json" - - def is_host_available(self) -> bool: - return self.get_config_path().parent.exists() +from hatch.mcp_host_config.adapters.base import BaseAdapter, AdapterValidationError +from hatch.mcp_host_config.fields import UNIVERSAL_FIELDS + +class NewHostAdapter(BaseAdapter): + @property + def host_name(self) -> str: + return "new-host" + + def get_supported_fields(self) -> FrozenSet[str]: + return UNIVERSAL_FIELDS | frozenset({"your_specific_field"}) + + def validate(self, config: MCPServerConfig) -> None: + """DEPRECATED: Use validate_filtered() instead.""" + pass + + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + has_command = "command" in filtered + has_url = "url" in filtered + if not has_command and not has_url: + raise AdapterValidationError("Need command or url") + if has_command and has_url: + raise AdapterValidationError("Only one transport allowed") + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + filtered = self.filter_fields(config) + self.validate_filtered(filtered) + return filtered ``` -**Full implementation** (host with unique fields): See [Implementation Guide](../implementation_guides/mcp_host_configuration_extension.md). - -### Extending Validation Rules - -Host strategies can implement custom validation: - -- **Path requirements**: Some hosts require absolute paths -- **Configuration format**: Validate against host-specific schemas -- **Feature support**: Check if host supports specific server features - -### Custom Configuration Formats - -Each strategy handles its own configuration format: - -- **JSON structure**: Most hosts use JSON configuration files -- **Nested keys**: Some hosts use nested configuration structures -- **Key naming**: Different hosts may use different key names for the same concept +See [Implementation Guide](../implementation_guides/mcp_host_configuration_extension.md) for complete instructions. ## Design Patterns -### Decorator Registration Pattern +### Declarative Field Support -Follows established Hatchling patterns for automatic component discovery: +Each adapter declares its supported fields as a `FrozenSet`: ```python -# Registry class with decorator method -class MCPHostRegistry: - @classmethod - def register(cls, host_type: MCPHostType): - def decorator(strategy_class): - cls._strategies[host_type] = strategy_class - return strategy_class - return decorator - -# Convenience function -def register_host_strategy(host_type: MCPHostType): - return MCPHostRegistry.register(host_type) +class YourAdapter(BaseAdapter): + def get_supported_fields(self) -> FrozenSet[str]: + return UNIVERSAL_FIELDS | frozenset({"your_field"}) ``` -### Family-Based Inheritance +The base class provides `filter_fields()` which: +1. Filters to only supported fields +2. Removes excluded fields (`name`) +3. Removes `None` values + +### Field Mappings (Optional) -Reduces code duplication through shared base classes: +If your host uses different field names: -- **Common validation logic** in family base classes -- **Shared configuration handling** for similar platforms -- **Consistent behavior** across related host types +```python +CODEX_FIELD_MAPPINGS = { + "args": "arguments", # Universal β†’ Codex naming + "headers": "http_headers", # Universal β†’ Codex naming +} +``` ### Atomic Operations Pattern @@ -250,45 +363,59 @@ All configuration changes use atomic operations: 3. **Verify success** and update state 4. **Clean up** or rollback on failure -## Testing Strategy - -The system includes comprehensive testing: - -- **Model validation tests**: Pydantic model behavior and validation rules -- **Decorator registration tests**: Automatic registration and inheritance patterns -- **Configuration manager tests**: Core operations and error handling -- **Environment integration tests**: Data structure compatibility -- **Backup integration tests**: Atomic operations and rollback behavior - -## Implementation Notes - -### Module Organization +## Module Organization ``` hatch/mcp_host_config/ -β”œβ”€β”€ __init__.py # Public API and registration triggering -β”œβ”€β”€ models.py # Pydantic models and data structures +β”œβ”€β”€ __init__.py # Public API exports +β”œβ”€β”€ models.py # MCPServerConfig, MCPHostType, HostConfiguration +β”œβ”€β”€ fields.py # Field constants (UNIVERSAL_FIELDS, EXCLUDED_ALWAYS, etc.) +β”œβ”€β”€ reporting.py # User feedback reporting system β”œβ”€β”€ host_management.py # Registry and configuration manager -└── strategies.py # Host strategy implementations +β”œβ”€β”€ strategies.py # Host strategy implementations (I/O) +β”œβ”€β”€ backup.py # Backup manager and atomic operations +└── adapters/ + β”œβ”€β”€ __init__.py # Adapter exports + β”œβ”€β”€ base.py # BaseAdapter abstract class + β”œβ”€β”€ registry.py # AdapterRegistry + β”œβ”€β”€ claude.py # ClaudeAdapter + β”œβ”€β”€ vscode.py # VSCodeAdapter + β”œβ”€β”€ cursor.py # CursorAdapter + β”œβ”€β”€ gemini.py # GeminiAdapter + β”œβ”€β”€ kiro.py # KiroAdapter + β”œβ”€β”€ codex.py # CodexAdapter + └── lmstudio.py # LMStudioAdapter ``` -### Import Behavior +## Error Handling + +The system uses both exceptions and result objects: -The `__init__.py` module imports `strategies` to trigger decorator registration: +- **Validation errors**: `AdapterValidationError` with field and host context +- **Configuration operations**: `ConfigurationResult` with success status and messages ```python -# This import triggers @register_host_strategy decorators -from . import strategies +try: + adapter.validate(config) +except AdapterValidationError as e: + print(f"Validation failed: {e.message}") + print(f"Field: {e.field}, Host: {e.host_name}") ``` -This ensures all strategies are automatically registered when the package is imported. +## Testing Strategy + +The test architecture uses a data-driven approach with property-based assertions: -### Error Handling Philosophy +| Tier | Location | Purpose | Approach | +|------|----------|---------|----------| +| Unit | `tests/unit/mcp/` | Adapter protocol, model validation, registry | Traditional | +| Integration | `tests/integration/mcp/` | Cross-host sync (64 pairs), host config (8 hosts) | Data-driven | +| Regression | `tests/regression/mcp/` | Validation bugs, field filtering (211+ tests) | Data-driven | -The system uses result objects rather than exceptions for configuration operations: +**Data-driven infrastructure** (`tests/test_data/mcp_adapters/`): -- **ConfigurationResult**: Contains success status, error messages, and operation details -- **Graceful degradation**: Operations continue when possible, reporting partial failures -- **Detailed error reporting**: Error messages include context and suggested solutions +- `canonical_configs.json`: Canonical config values for all 8 hosts +- `host_registry.py`: HostRegistry derives metadata from fields.py +- `assertions.py`: Property-based assertions verify adapter contracts -This approach provides better control flow for CLI operations and enables comprehensive error reporting to users. +Adding a new host requires zero test code changes β€” only a fixture entry and fields.py update. diff --git a/docs/articles/devs/architecture/system_overview.md b/docs/articles/devs/architecture/system_overview.md index a17bfda..4299e66 100644 --- a/docs/articles/devs/architecture/system_overview.md +++ b/docs/articles/devs/architecture/system_overview.md @@ -22,9 +22,16 @@ Hatch is a sophisticated package management system designed for the CrackingShel The command-line interface provides the primary user interaction point: -- **`hatch/cli_hatch.py`** - Command-line interface with argument parsing and validation +- **`hatch/cli/`** - Modular CLI package with handler-based architecture + - `__main__.py` - Entry point with argument parsing and routing + - `cli_utils.py` - Shared utilities and formatting infrastructure + - `cli_env.py` - Environment management handlers + - `cli_package.py` - Package management handlers + - `cli_mcp.py` - MCP host configuration handlers + - `cli_system.py` - System-level command handlers - Delegates operations to appropriate management components - Provides consistent user experience across all operations +- Uses unified output formatting (ResultReporter, TableFormatter) ### Environment Management Layer diff --git a/docs/articles/devs/contribution_guides/release_policy.md b/docs/articles/devs/contribution_guides/release_policy.md index e9ac621..8c6fb7e 100644 --- a/docs/articles/devs/contribution_guides/release_policy.md +++ b/docs/articles/devs/contribution_guides/release_policy.md @@ -157,7 +157,7 @@ Examples of release-triggering commits: ```bash # Triggers patch version (0.7.0 β†’ 0.7.1) feat: add new package registry support -fix: resolve dependency resolution timeout +fix: resolve dependency resolution timeout docs: update package manager documentation refactor: simplify package installation logic style: fix code formatting diff --git a/docs/articles/devs/development_processes/developer_onboarding.md b/docs/articles/devs/development_processes/developer_onboarding.md index 9449298..49048eb 100644 --- a/docs/articles/devs/development_processes/developer_onboarding.md +++ b/docs/articles/devs/development_processes/developer_onboarding.md @@ -69,7 +69,13 @@ hatch --help ```txt hatch/ -β”œβ”€β”€ cli_hatch.py # Main CLI entry point +β”œβ”€β”€ cli/ # Modular CLI package +β”‚ β”œβ”€β”€ __main__.py # Entry point and routing +β”‚ β”œβ”€β”€ cli_utils.py # Shared utilities +β”‚ β”œβ”€β”€ cli_env.py # Environment handlers +β”‚ β”œβ”€β”€ cli_package.py # Package handlers +β”‚ β”œβ”€β”€ cli_mcp.py # MCP handlers +β”‚ └── cli_system.py # System handlers β”œβ”€β”€ environment_manager.py # Environment lifecycle management β”œβ”€β”€ package_loader.py # Package loading and validation β”œβ”€β”€ registry_retriever.py # Package downloads and caching diff --git a/docs/articles/devs/implementation_guides/adding_cli_commands.md b/docs/articles/devs/implementation_guides/adding_cli_commands.md new file mode 100644 index 0000000..71edda8 --- /dev/null +++ b/docs/articles/devs/implementation_guides/adding_cli_commands.md @@ -0,0 +1,550 @@ +# Adding CLI Commands + +This guide provides step-by-step instructions for adding new commands to the Hatch CLI, following the established modular architecture. + +## Prerequisites + +Before adding a new command, familiarize yourself with: + +- [CLI Architecture](../architecture/cli_architecture.md): Understand the overall design +- [Component Architecture](../architecture/component_architecture.md): Understand how CLI integrates with managers +- Existing handler implementations in `hatch/cli/cli_*.py` + +## Step-by-Step Process + +### 1. Determine Command Category + +Identify which handler module your command belongs to: + +- **`cli_env.py`**: Environment lifecycle and Python environment operations +- **`cli_package.py`**: Package installation, removal, and synchronization +- **`cli_mcp.py`**: MCP host configuration, discovery, and backup +- **`cli_system.py`**: System-level operations (package creation, validation) + +**Decision Criteria**: +- Does it manage environment state? β†’ `cli_env.py` +- Does it install/remove packages? β†’ `cli_package.py` +- Does it configure MCP hosts? β†’ `cli_mcp.py` +- Does it operate on packages outside environments? β†’ `cli_system.py` + +### 2. Add Argument Parser Setup + +In `hatch/cli/__main__.py`, add a parser setup function or extend an existing one: + +**For new top-level commands**: +```python +def _setup_mycommand_command(subparsers): + """Set up 'hatch mycommand' command parser.""" + mycommand_parser = subparsers.add_parser( + "mycommand", help="Brief description of command" + ) + mycommand_parser.add_argument("required_arg", help="Required argument") + mycommand_parser.add_argument( + "--optional-flag", action="store_true", help="Optional flag" + ) + mycommand_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) +``` + +**For subcommands under existing commands**: +```python +def _setup_env_commands(subparsers): + # ... existing code ... + + # Add new subcommand + env_newcmd_parser = env_subparsers.add_parser( + "newcmd", help="New environment subcommand" + ) + env_newcmd_parser.add_argument("name", help="Environment name") + env_newcmd_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) +``` + +**Standard Arguments to Include**: +- `--dry-run`: For mutation commands (preview without execution) +- `--auto-approve`: For destructive operations (skip confirmation) +- `--json`: For list/show commands (JSON output format) +- `--env` or `-e`: For commands that operate on environments + +**Call the setup function** in `main()`: +```python +def main(): + # ... existing code ... + _setup_mycommand_command(subparsers) # Add this line + # ... rest of main ... +``` + +### 3. Implement Handler Function + +In the appropriate handler module (`cli_env.py`, `cli_package.py`, etc.), implement the handler: + +**Handler Template**: +```python +def handle_mycommand(args: Namespace) -> int: + """Handle 'hatch mycommand' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - mcp_manager: MCPHostConfigurationManager instance (if needed) + - required_arg: Description of required argument + - optional_flag: Description of optional flag + - dry_run: Preview changes without execution + + Returns: + Exit code (0 for success, 1 for error) + """ + from hatch.cli.cli_utils import ( + EXIT_SUCCESS, + EXIT_ERROR, + ResultReporter, + ConsequenceType, + request_confirmation, + format_info, + ) + + # Extract arguments + env_manager = args.env_manager + required_arg = args.required_arg + optional_flag = getattr(args, "optional_flag", False) + dry_run = getattr(args, "dry_run", False) + + # Create reporter for unified output + reporter = ResultReporter("hatch mycommand", dry_run=dry_run) + + # Add consequences (actions to be performed) + reporter.add(ConsequenceType.CREATE, f"Resource '{required_arg}'") + + # Handle dry-run + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt and request confirmation (for mutation commands) + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + if not request_confirmation("Proceed?"): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Execute operation + try: + # Call manager methods to perform actual work + success = env_manager.some_operation(required_arg) + + if success: + reporter.report_result() + return EXIT_SUCCESS + else: + reporter.report_error(f"Failed to perform operation on '{required_arg}'") + return EXIT_ERROR + except Exception as e: + reporter.report_error( + "Operation failed", + details=[f"Reason: {str(e)}"] + ) + return EXIT_ERROR +``` + +**Handler Patterns by Command Type**: + +#### Mutation Commands (Create, Update, Delete) +```python +# 1. Build consequences +reporter.add(ConsequenceType.CREATE, "Resource 'name'") + +# 2. Handle dry-run early +if dry_run: + reporter.report_result() + return EXIT_SUCCESS + +# 3. Show prompt and confirm +prompt = reporter.report_prompt() +if prompt: + print(prompt) +if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + +# 4. Execute +success = manager.operation() + +# 5. Report results +if success: + reporter.report_result() + return EXIT_SUCCESS +else: + reporter.report_error("Operation failed") + return EXIT_ERROR +``` + +#### List Commands +```python +from hatch.cli.cli_utils import TableFormatter, ColumnDef + +# Get data +items = manager.list_items() + +# JSON output (if requested) +if getattr(args, 'json', False): + import json + print(json.dumps({"items": items}, indent=2)) + return EXIT_SUCCESS + +# Table output +print("Items:") +columns = [ + ColumnDef(name="Name", width=20), + ColumnDef(name="Status", width=10), + ColumnDef(name="Count", width="auto", align="right"), +] +formatter = TableFormatter(columns) + +for item in items: + formatter.add_row([item.name, item.status, str(item.count)]) + +print(formatter.render()) +return EXIT_SUCCESS +``` + +#### Show Commands (Detailed Views) +```python +from hatch.cli.cli_utils import highlight + +# Get detailed data +item = manager.get_item(name) + +if not item: + format_validation_error(ValidationError( + f"Item '{name}' not found", + field="name", + suggestion="Use 'hatch list' to see available items" + )) + return EXIT_ERROR + +# Hierarchical output +separator = "═" * 79 +print(separator) +print(f"Item: {highlight(item.name)}") +print(f" Status: {item.status}") +print(f" Created: {item.created_at}") +print() + +print(f" Details ({len(item.details)}):") +for detail in item.details: + print(f" {highlight(detail.name)}") + print(f" Value: {detail.value}") + print() + +return EXIT_SUCCESS +``` + +### 4. Add Routing Logic + +In `hatch/cli/__main__.py`, add routing for your command: + +**For new top-level commands**: +```python +def main(): + # ... existing code ... + + # Route commands + if args.command == "mycommand": + from hatch.cli.cli_system import handle_mycommand + return handle_mycommand(args) + # ... existing routes ... +``` + +**For subcommands**: +```python +def _route_env_command(args): + """Route environment commands to handlers.""" + from hatch.cli.cli_env import ( + # ... existing imports ... + handle_env_newcmd, # Add new handler + ) + + # ... existing routes ... + + elif args.env_command == "newcmd": + return handle_env_newcmd(args) + + # ... rest of routing ... +``` + +### 5. Choose Appropriate ConsequenceType + +Select the correct `ConsequenceType` for your operations: + +**Constructive (Green)**: +- `CREATE`: Creating new resources +- `ADD`: Adding items to collections +- `CONFIGURE`: Setting up configurations +- `INSTALL`: Installing dependencies +- `INITIALIZE`: Initializing environments + +**Recovery (Blue)**: +- `RESTORE`: Restoring from backups + +**Destructive (Red)**: +- `REMOVE`: Removing items from collections +- `DELETE`: Deleting resources permanently +- `CLEAN`: Cleaning up old data + +**Modification (Yellow)**: +- `SET`: Setting values +- `UPDATE`: Updating existing resources + +**Transfer (Magenta)**: +- `SYNC`: Synchronizing between systems + +**Informational (Cyan)**: +- `VALIDATE`: Validating data + +**No-op (Gray)**: +- `SKIP`: Skipping operations +- `EXISTS`: Resource already exists +- `UNCHANGED`: No changes needed + +### 6. Handle Nested Consequences (Optional) + +For field-level details under resource-level actions: + +```python +# Resource-level consequence with field-level children +children = [ + Consequence(ConsequenceType.UPDATE, "field1: 'old' β†’ 'new'"), + Consequence(ConsequenceType.SKIP, "field2: unsupported by host"), + Consequence(ConsequenceType.UNCHANGED, "field3: 'value'"), +] + +reporter.add( + ConsequenceType.CONFIGURE, + "Server 'my-server' on 'claude-desktop'", + children=children +) +``` + +### 7. Add Error Handling + +Use structured error reporting: + +```python +from hatch.cli.cli_utils import ( + ValidationError, + format_validation_error, +) + +# Validation errors +try: + host_type = MCPHostType(host) +except ValueError: + format_validation_error(ValidationError( + f"Invalid host '{host}'", + field="--host", + suggestion=f"Supported hosts: {', '.join(h.value for h in MCPHostType)}" + )) + return EXIT_ERROR + +# Operation errors +if not success: + reporter.report_error( + "Operation failed", + details=[ + f"Resource: {resource_name}", + f"Reason: {error_message}" + ] + ) + return EXIT_ERROR + +# Partial success +reporter.report_partial_success( + "Partial operation", + successes=["item1", "item2"], + failures=[("item3", "reason"), ("item4", "reason")] +) +``` + +### 8. Test Your Command + +#### Manual Testing +```bash +# Test help output +hatch mycommand --help + +# Test dry-run mode +hatch mycommand arg --dry-run + +# Test actual execution +hatch mycommand arg + +# Test error cases +hatch mycommand invalid-arg + +# Test JSON output (if applicable) +hatch mycommand --json + +# Test with NO_COLOR +NO_COLOR=1 hatch mycommand arg +``` + +#### Unit Testing +Create tests in `tests/unit/cli/` or `tests/regression/cli/`: + +```python +def test_handle_mycommand_success(mock_env_manager): + """Test successful command execution.""" + args = Namespace( + env_manager=mock_env_manager, + required_arg="test", + optional_flag=False, + dry_run=False, + ) + + result = handle_mycommand(args) + + assert result == EXIT_SUCCESS + mock_env_manager.some_operation.assert_called_once_with("test") + +def test_handle_mycommand_dry_run(mock_env_manager): + """Test dry-run mode.""" + args = Namespace( + env_manager=mock_env_manager, + required_arg="test", + dry_run=True, + ) + + result = handle_mycommand(args) + + assert result == EXIT_SUCCESS + mock_env_manager.some_operation.assert_not_called() +``` + +### 9. Update Documentation + +After implementing your command: + +1. **CLI Reference**: Add command documentation to `docs/articles/users/CLIReference.md` +2. **Tutorials**: Add usage examples if appropriate +3. **Changelog**: Document the new command in `CHANGELOG.md` + +## Common Patterns and Gotchas + +### Pattern: Accessing Optional Arguments +Always use `getattr()` with defaults for optional arguments: +```python +dry_run = getattr(args, "dry_run", False) +auto_approve = getattr(args, "auto_approve", False) +env_name = getattr(args, "env", None) +``` + +### Pattern: Environment Name Resolution +Many commands default to the current environment: +```python +env_name = getattr(args, "env", None) or env_manager.get_current_environment() +``` + +### Pattern: Regex Pattern Filtering +For list commands with pattern filtering: +```python +import re + +pattern = getattr(args, 'pattern', None) +if pattern: + try: + regex = re.compile(pattern) + items = [item for item in items if regex.search(item.name)] + except re.error as e: + format_validation_error(ValidationError( + f"Invalid regex pattern: {e}", + field="--pattern", + suggestion="Use a valid Python regex pattern" + )) + return EXIT_ERROR +``` + +### Gotcha: Manager Initialization +Managers are initialized in `main()` and attached to `args`. Don't create new manager instances in handlers: +```python +# βœ… Correct +env_manager = args.env_manager + +# ❌ Wrong +env_manager = HatchEnvironmentManager() # Creates new instance! +``` + +### Gotcha: Exit Codes +Always return `EXIT_SUCCESS` or `EXIT_ERROR`, never raw integers: +```python +# βœ… Correct +return EXIT_SUCCESS + +# ❌ Wrong +return 0 # Use constant for clarity +``` + +### Gotcha: Confirmation Prompts +Always check `auto_approve` before prompting: +```python +# βœ… Correct +if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + +# ❌ Wrong +if not request_confirmation("Proceed?"): # Ignores auto_approve! + return EXIT_SUCCESS +``` + +### Gotcha: Dry-Run Handling +Handle dry-run AFTER building consequences but BEFORE execution: +```python +# βœ… Correct +reporter.add(ConsequenceType.CREATE, "Resource") +if dry_run: + reporter.report_result() + return EXIT_SUCCESS +# ... execute operation ... + +# ❌ Wrong +if dry_run: + return EXIT_SUCCESS # Consequences not shown! +reporter.add(ConsequenceType.CREATE, "Resource") +``` + +## Examples from Codebase + +### Simple Mutation Command +See `handle_env_use()` in `hatch/cli/cli_env.py`: +- Single consequence +- No confirmation needed (non-destructive) +- Simple success/error reporting + +### Complex Mutation Command +See `handle_package_sync()` in `hatch/cli/cli_package.py`: +- Multiple consequences (packages + dependencies) +- Confirmation required +- Nested consequences from conversion reports +- Partial success handling + +### List Command with Filtering +See `handle_env_list()` in `hatch/cli/cli_env.py`: +- Regex pattern filtering +- JSON output support +- Table formatting with auto-width columns + +### Show Command with Hierarchy +See `handle_mcp_show_hosts()` in `hatch/cli/cli_mcp.py`: +- Hierarchical output with separators +- Entity highlighting with `highlight()` +- Sensitive data masking + +## Related Documentation + +- [CLI Architecture](../architecture/cli_architecture.md): Overall design and components +- [Testing Standards](../development_processes/testing_standards.md): Testing requirements +- [CLI Reference](../../users/CLIReference.md): User-facing command documentation diff --git a/docs/articles/devs/implementation_guides/adding_installers.md b/docs/articles/devs/implementation_guides/adding_installers.md index 8f56a2b..0aaf010 100644 --- a/docs/articles/devs/implementation_guides/adding_installers.md +++ b/docs/articles/devs/implementation_guides/adding_installers.md @@ -42,11 +42,11 @@ class MyInstaller(DependencyInstaller): @property def installer_type(self) -> str: return "my-type" # What goes in dependency["type"] - + def can_install(self, dependency: Dict[str, Any]) -> bool: # Return True if you can handle this dependency return dependency.get("type") == "my-type" - + def install(self, dependency: Dict[str, Any], context: InstallationContext) -> InstallationResult: # Your installation logic here name = dependency["name"] @@ -110,4 +110,4 @@ Look at existing installers to understand patterns: **Context matters:** Use the `InstallationContext` for target paths, environment info, and progress reporting. -**Error messages:** Make them actionable. "Permission denied installing X" is better than "Installation failed". \ No newline at end of file +**Error messages:** Make them actionable. "Permission denied installing X" is better than "Installation failed". diff --git a/docs/articles/devs/implementation_guides/index.md b/docs/articles/devs/implementation_guides/index.md index 134d273..e82d8ab 100644 --- a/docs/articles/devs/implementation_guides/index.md +++ b/docs/articles/devs/implementation_guides/index.md @@ -15,6 +15,7 @@ You're working on Hatch and need to: ### Adding Functionality +- **[Adding CLI Commands](./adding_cli_commands.md)** - Add new commands to the CLI (10-minute read) - **[Adding New Installers](./adding_installers.md)** - Support new dependency types (5-minute read) - **[Package Loading Extensions](./package_loader_extensions.md)** - Custom package formats and validation (3-minute read) diff --git a/docs/articles/devs/implementation_guides/installation_orchestration.md b/docs/articles/devs/implementation_guides/installation_orchestration.md index 87f745d..d5277ca 100644 --- a/docs/articles/devs/implementation_guides/installation_orchestration.md +++ b/docs/articles/devs/implementation_guides/installation_orchestration.md @@ -36,30 +36,30 @@ class CustomInstallationOrchestrator(InstallationOrchestrator): # Pre-installation validation if not self._validate_installation_requirements(package_name, version): raise InstallationError(f"Requirements not met for {package_name}") - + # Custom installation steps package_path = self._download_and_prepare(package_name, version) self._run_pre_install_hooks(package_path) - + # Standard installation success = super().install_package(package_name, version, target_env) - + if success: self._run_post_install_hooks(package_path, target_env) self._update_installation_registry(package_name, version, target_env) - + return success - + def _validate_installation_requirements(self, package_name: str, version: str) -> bool: # Check system requirements, disk space, permissions, etc. return True - + def _run_pre_install_hooks(self, package_path: Path): # Custom pre-installation tasks hook_script = package_path / "pre_install.py" if hook_script.exists(): subprocess.run([sys.executable, str(hook_script)], check=True) - + def _run_post_install_hooks(self, package_path: Path, target_env: str): # Custom post-installation tasks hook_script = package_path / "post_install.py" @@ -76,30 +76,30 @@ class SmartDependencyOrchestrator(InstallationOrchestrator): def __init__(self, conflict_resolution="latest"): super().__init__() self.conflict_resolution = conflict_resolution - + def resolve_dependencies(self, package_name: str, version: str) -> List[Tuple[str, str]]: # Get package metadata metadata = self.registry_retriever.get_package_metadata(package_name, version) dependencies = metadata.get("dependencies", {}) - + # Build dependency tree resolved = [] for dep_name, dep_constraint in dependencies.items(): dep_version = self._resolve_version_constraint(dep_name, dep_constraint) resolved.append((dep_name, dep_version)) - + # Recursively resolve dependencies sub_deps = self.resolve_dependencies(dep_name, dep_version) resolved.extend(sub_deps) - + # Handle conflicts return self._resolve_conflicts(resolved) - + def _resolve_version_constraint(self, package_name: str, constraint: str) -> str: available_versions = self.registry_retriever.get_package_versions(package_name) # Apply constraint logic (semver, etc.) return self._pick_best_version(available_versions, constraint) - + def _resolve_conflicts(self, dependencies: List[Tuple[str, str]]) -> List[Tuple[str, str]]: # Group by package name by_package = {} @@ -107,7 +107,7 @@ class SmartDependencyOrchestrator(InstallationOrchestrator): if name not in by_package: by_package[name] = [] by_package[name].append(version) - + # Resolve conflicts based on strategy resolved = [] for package_name, versions in by_package.items(): @@ -116,7 +116,7 @@ class SmartDependencyOrchestrator(InstallationOrchestrator): else: chosen_version = self._choose_version(versions) resolved.append((package_name, chosen_version)) - + return resolved ``` @@ -126,22 +126,22 @@ class SmartDependencyOrchestrator(InstallationOrchestrator): class MultiEnvOrchestrator(InstallationOrchestrator): def install_to_environments(self, package_name: str, version: str, environments: List[str]) -> Dict[str, bool]: results = {} - + for env in environments: try: # Environment-specific configuration env_config = self._get_environment_config(env) - + # Install with environment-specific settings success = self._install_to_specific_env(package_name, version, env, env_config) results[env] = success - + except Exception as e: results[env] = False self._log_installation_error(env, package_name, version, e) - + return results - + def _get_environment_config(self, env: str) -> Dict: config_map = { "development": {"debug": True, "test_dependencies": True}, @@ -149,7 +149,7 @@ class MultiEnvOrchestrator(InstallationOrchestrator): "testing": {"debug": True, "mock_external": True} } return config_map.get(env, {}) - + def _install_to_specific_env(self, package_name: str, version: str, env: str, config: Dict) -> bool: # Custom installation logic per environment if env == "production": @@ -167,20 +167,20 @@ class IntegratedOrchestrator(InstallationOrchestrator): def __init__(self, external_tools: Dict[str, str] = None): super().__init__() self.external_tools = external_tools or {} - + def install_package(self, package_name: str, version: str = None, target_env: str = None) -> bool: # Check if package requires external tools metadata = self.registry_retriever.get_package_metadata(package_name, version) external_deps = metadata.get("external_dependencies", []) - + # Install external dependencies first for ext_dep in external_deps: if not self._install_external_dependency(ext_dep): raise InstallationError(f"Failed to install external dependency: {ext_dep}") - + # Proceed with standard installation return super().install_package(package_name, version, target_env) - + def _install_external_dependency(self, dependency: str) -> bool: # Handle different external tools if dependency.startswith("apt:"): @@ -215,10 +215,10 @@ class ValidatingOrchestrator(InstallationOrchestrator): def install_package(self, package_name: str, version: str = None, target_env: str = None) -> bool: # Download and validate package before installation package_path = self.registry_retriever.download_package(package_name, version, self.temp_dir) - + if not self.package_validator.validate_package(package_path): raise InstallationError(f"Package validation failed: {package_name}") - + return super().install_package(package_name, version, target_env) ``` @@ -230,12 +230,12 @@ class ConfigurableOrchestrator(InstallationOrchestrator): super().__init__() self.config = self._load_config(config_path) self._setup_from_config() - + def _setup_from_config(self): # Configure components based on config file if "registry" in self.config: self.registry_retriever = self._create_registry_from_config(self.config["registry"]) - + if "installers" in self.config: self._register_installers_from_config(self.config["installers"]) ``` @@ -253,14 +253,14 @@ class TestCustomOrchestrator(unittest.TestCase): registry_retriever=self.mock_registry, environment_manager=self.mock_env_manager ) - + def test_multi_step_installation(self): # Set up mocks self.mock_registry.download_package.return_value = Path("/tmp/test-pkg") - + # Test installation success = self.orchestrator.install_package("test-pkg", "1.0.0") - + # Verify all steps were called self.assertTrue(success) self.mock_registry.download_package.assert_called_once() diff --git a/docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md b/docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md index e5fad58..101be90 100644 --- a/docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md +++ b/docs/articles/devs/implementation_guides/mcp_host_configuration_extension.md @@ -1,861 +1,393 @@ -# Extending MCP Host Configuration - -**Quick Start:** Copy an existing strategy, modify configuration paths and validation, add decorator. Most strategies are 50-100 lines. - -## Before You Start: Integration Checklist - -Use this checklist to plan your implementation. Missing integration points cause incomplete functionality. - -| Integration Point | Required? | When Needed | -|-------------------|-----------|-------------| -| ☐ Host type enum | Always | All hosts | -| ☐ Strategy class | Always | All hosts | -| ☐ Backup integration | Always | All hosts - **commonly missed** | -| ☐ Host-specific model | Sometimes | Host has unique config fields | -| ☐ CLI arguments | Sometimes | Host has unique config fields | -| ☐ Test infrastructure | Always | All hosts | - -> **Lesson learned:** The backup system integration is frequently overlooked during planning but is mandatory for all hosts. Plan for it upfront. - -## When You Need This - -You want Hatch to configure MCP servers on a new host platform: - -- A code editor not yet supported (Zed, Neovim, etc.) -- A custom MCP host implementation -- Cloud-based development environments -- Specialized MCP server platforms - -## The Pattern - -All host strategies implement `MCPHostStrategy` and get registered with `@register_host_strategy`. The configuration manager finds the right strategy by host type and delegates operations. - -**Core interface** (from `hatch/mcp_host_config/host_management.py`): - -```python -@register_host_strategy(MCPHostType.YOUR_HOST) -class YourHostStrategy(MCPHostStrategy): - def get_config_path(self) -> Optional[Path]: # Where is the config file? - def is_host_available(self) -> bool: # Is this host installed/available? - def get_config_key(self) -> str: # Root key for MCP servers in config (default: "mcpServers") - def validate_server_config(self, server_config: MCPServerConfig) -> bool: # Is this config valid? - def read_configuration(self) -> HostConfiguration: # Read current config - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: # Write config -``` - -## Implementation Steps - -### 1. Choose Your Base Class - -**For similar platforms**, inherit from a family base class. These provide complete implementations of `read_configuration()` and `write_configuration()` - you typically only override `get_config_path()` and `is_host_available()`: - -```python -# If your host is similar to Claude (accepts any command or URL) -class YourHostStrategy(ClaudeHostStrategy): - # Inherits read/write logic, just override: - # - get_config_path() - # - is_host_available() - -# If your host is similar to Cursor (flexible, supports remote servers) -class YourHostStrategy(CursorBasedHostStrategy): - # Inherits read/write logic, just override: - # - get_config_path() - # - is_host_available() - -# For unique requirements or different config structure -class YourHostStrategy(MCPHostStrategy): - # Implement all 6 methods yourself -``` - -**Existing host types** already supported: -- `CLAUDE_DESKTOP` - Claude Desktop app -- `CLAUDE_CODE` - Claude for VS Code -- `VSCODE` - VS Code with MCP extension -- `CURSOR` - Cursor IDE -- `LMSTUDIO` - LM Studio -- `GEMINI` - Google Gemini CLI -- `KIRO` - Kiro IDE - -### 2. Add Host Type - -Add your host to the enum in `models.py`: - -```python -class MCPHostType(str, Enum): - # ... existing types ... - YOUR_HOST = "your-host" -``` - -### 3. Implement Strategy Class - -**If inheriting from `ClaudeHostStrategy` or `CursorBasedHostStrategy`** (recommended): - -```python -@register_host_strategy(MCPHostType.YOUR_HOST) -class YourHostStrategy(ClaudeHostStrategy): # or CursorBasedHostStrategy - """Configuration strategy for Your Host.""" - - def get_config_path(self) -> Optional[Path]: - """Return path to your host's configuration file.""" - return Path.home() / ".your_host" / "config.json" - - def is_host_available(self) -> bool: - """Check if your host is installed/available.""" - config_path = self.get_config_path() - return config_path and config_path.parent.exists() - - # Inherits from base class: - # - read_configuration() - # - write_configuration() - # - validate_server_config() - # - get_config_key() (returns "mcpServers" by default) -``` - -**If implementing from scratch** (for unique config structures): - -```python -@register_host_strategy(MCPHostType.YOUR_HOST) -class YourHostStrategy(MCPHostStrategy): - """Configuration strategy for Your Host.""" - - def get_config_path(self) -> Optional[Path]: - """Return path to your host's configuration file.""" - return Path.home() / ".your_host" / "config.json" - - def is_host_available(self) -> bool: - """Check if your host is installed/available.""" - config_path = self.get_config_path() - return config_path and config_path.parent.exists() - - def get_config_key(self) -> str: - """Root key for MCP servers in config file.""" - return "mcpServers" # Most hosts use this; override if different - - def validate_server_config(self, server_config: MCPServerConfig) -> bool: - """Validate server config for your host's requirements.""" - # Accept local servers (command-based) - if server_config.command: - return True - # Accept remote servers (URL-based) - if server_config.url: - return True - return False - - def read_configuration(self) -> HostConfiguration: - """Read and parse host configuration.""" - config_path = self.get_config_path() - if not config_path or not config_path.exists(): - return HostConfiguration() - - try: - with open(config_path, 'r') as f: - config_data = json.load(f) - - # Extract MCP servers from your host's config structure - mcp_servers = config_data.get(self.get_config_key(), {}) - - # Convert to MCPServerConfig objects - servers = {} - for name, server_data in mcp_servers.items(): - try: - servers[name] = MCPServerConfig(**server_data) - except Exception as e: - logger.warning(f"Invalid server config for {name}: {e}") - continue - - return HostConfiguration(servers=servers) - - except Exception as e: - logger.error(f"Failed to read configuration: {e}") - return HostConfiguration() - - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write configuration to host file.""" - config_path = self.get_config_path() - if not config_path: - return False - - try: - # Ensure parent directory exists - config_path.parent.mkdir(parents=True, exist_ok=True) - - # Read existing configuration to preserve non-MCP settings - existing_config = {} - if config_path.exists(): - try: - with open(config_path, 'r') as f: - existing_config = json.load(f) - except Exception: - pass # Start with empty config if read fails - - # Convert MCPServerConfig objects to dict - servers_dict = {} - for name, server_config in config.servers.items(): - servers_dict[name] = server_config.model_dump(exclude_none=True) - - # Update MCP servers section (preserves other settings) - existing_config[self.get_config_key()] = servers_dict - - # Write atomically using temp file - temp_path = config_path.with_suffix('.tmp') - with open(temp_path, 'w') as f: - json.dump(existing_config, f, indent=2) - - # Atomic replace - temp_path.replace(config_path) - return True - - except Exception as e: - logger.error(f"Failed to write configuration: {e}") - return False -``` - -### 4. Integrate Backup System (Required) - -All host strategies must integrate with the backup system for data safety. This is **mandatory** - don't skip it. - -**Current implementation status:** -- Family base classes (`ClaudeHostStrategy`, `CursorBasedHostStrategy`) use atomic temp-file writes but not the full backup manager -- `KiroHostStrategy` demonstrates full backup manager integration with `MCPHostConfigBackupManager` and `AtomicFileOperations` - -**For new implementations**: Add backup integration to `write_configuration()`: - -```python -from .backup import MCPHostConfigBackupManager, AtomicFileOperations - -def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - config_path = self.get_config_path() - if not config_path: - return False - - try: - config_path.parent.mkdir(parents=True, exist_ok=True) - - # Read existing config to preserve non-MCP settings - existing_data = {} - if config_path.exists(): - with open(config_path, 'r', encoding='utf-8') as f: - existing_data = json.load(f) - - # Update MCP servers section - servers_data = { - name: server.model_dump(exclude_unset=True) - for name, server in config.servers.items() - } - existing_data[self.get_config_key()] = servers_data - - # Use atomic write with backup support - backup_manager = MCPHostConfigBackupManager() - atomic_ops = AtomicFileOperations() - atomic_ops.atomic_write_with_backup( - file_path=config_path, - data=existing_data, - backup_manager=backup_manager, - hostname="your-host", # Must match your MCPHostType value - skip_backup=no_backup - ) - return True - - except Exception as e: - logger.error(f"Failed to write configuration: {e}") - return False -``` - -**Key points:** -- `hostname` parameter must match your `MCPHostType` enum value (e.g., `"kiro"` for `MCPHostType.KIRO`) -- `skip_backup` respects the `no_backup` parameter passed to `write_configuration()` -- Atomic operations ensure config file integrity even if the process crashes - -### 5. Handle Configuration Format (Optional) - -Override configuration reading/writing only if your host has a non-standard format: - -```python -def read_configuration(self) -> HostConfiguration: - """Read current configuration from host.""" - config_path = self.get_config_path() - if not config_path or not config_path.exists(): - return HostConfiguration(servers={}) - - try: - with open(config_path, 'r') as f: - data = json.load(f) - - # Extract MCP servers from your host's format - servers_data = data.get(self.get_config_key(), {}) - servers = { - name: MCPServerConfig(**config) - for name, config in servers_data.items() - } - - return HostConfiguration(servers=servers) - except Exception as e: - raise ConfigurationError(f"Failed to read {self.get_config_path()}: {e}") - -def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write configuration to host.""" - config_path = self.get_config_path() - if not config_path: - return False - - # Create backup if requested - if not no_backup and config_path.exists(): - self._create_backup(config_path) - - try: - # Read existing config to preserve other settings - existing_data = {} - if config_path.exists(): - with open(config_path, 'r') as f: - existing_data = json.load(f) - - # Update MCP servers section - existing_data[self.get_config_key()] = { - name: server.model_dump(exclude_none=True) - for name, server in config.servers.items() - } - - # Write updated config - config_path.parent.mkdir(parents=True, exist_ok=True) - with open(config_path, 'w') as f: - json.dump(existing_data, f, indent=2) - - return True - except Exception as e: - self._restore_backup(config_path) # Rollback on failure - raise ConfigurationError(f"Failed to write {config_path}: {e}") -``` - -## Common Patterns - -### Standard JSON Configuration - -Most hosts use JSON with an `mcpServers` key: - -```json -{ - "mcpServers": { - "server-name": { - "command": "python", - "args": ["server.py"] - } - } -} -``` - -This is the default - no override needed. - -### Custom Configuration Key - -Some hosts use different root keys. Override `get_config_key()`: - -```python -def get_config_key(self) -> str: - """VS Code uses 'servers' instead of 'mcpServers'.""" - return "servers" -``` - -Example: VS Code uses `"servers"` directly: - -```json -{ - "servers": { - "server-name": { - "command": "python", - "args": ["server.py"] - } - } -} -``` - -### Nested Configuration Structures - -For hosts with deeply nested config, handle in `read_configuration()` and `write_configuration()`: - -```python -def read_configuration(self) -> HostConfiguration: - """Read from nested structure.""" - config_path = self.get_config_path() - if not config_path or not config_path.exists(): - return HostConfiguration() - - try: - with open(config_path, 'r') as f: - data = json.load(f) - - # Navigate nested structure - mcp_servers = data.get("mcp", {}).get("servers", {}) - - servers = {} - for name, server_data in mcp_servers.items(): - try: - servers[name] = MCPServerConfig(**server_data) - except Exception as e: - logger.warning(f"Invalid server config for {name}: {e}") - - return HostConfiguration(servers=servers) - except Exception as e: - logger.error(f"Failed to read configuration: {e}") - return HostConfiguration() - -def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write to nested structure.""" - config_path = self.get_config_path() - if not config_path: - return False - - try: - config_path.parent.mkdir(parents=True, exist_ok=True) - - # Read existing config - existing_config = {} - if config_path.exists(): - try: - with open(config_path, 'r') as f: - existing_config = json.load(f) - except Exception: - pass - - # Ensure nested structure exists - if "mcp" not in existing_config: - existing_config["mcp"] = {} - - # Convert servers - servers_dict = {} - for name, server_config in config.servers.items(): - servers_dict[name] = server_config.model_dump(exclude_none=True) - - # Update nested servers - existing_config["mcp"]["servers"] = servers_dict - - # Write atomically - temp_path = config_path.with_suffix('.tmp') - with open(temp_path, 'w') as f: - json.dump(existing_config, f, indent=2) - - temp_path.replace(config_path) - return True - except Exception as e: - logger.error(f"Failed to write configuration: {e}") - return False -``` - -### Platform-Specific Paths - -Different platforms have different config locations. Use `platform.system()` to detect: - -```python -import platform - -def get_config_path(self) -> Optional[Path]: - """Get platform-specific config path.""" - system = platform.system() - - if system == "Darwin": # macOS - return Path.home() / "Library" / "Application Support" / "YourHost" / "config.json" - elif system == "Windows": - return Path.home() / "AppData" / "Roaming" / "YourHost" / "config.json" - elif system == "Linux": - return Path.home() / ".config" / "yourhost" / "config.json" - - return None # Unsupported platform -``` - -**Example from codebase:** `ClaudeDesktopStrategy` uses this pattern for macOS, Windows, and Linux. - -## Testing Your Strategy - -### Test Categories - -Your implementation needs tests in these categories: - -| Category | Purpose | Location | -|----------|---------|----------| -| Strategy tests | Registration, paths, validation | `tests/regression/test_mcp_yourhost_host_strategy.py` | -| Backup tests | Backup creation, restoration | `tests/regression/test_mcp_yourhost_backup_integration.py` | -| Model tests | Field validation (if host-specific model) | `tests/regression/test_mcp_yourhost_model_validation.py` | -| CLI tests | Argument handling (if host-specific args) | `tests/regression/test_mcp_yourhost_cli_integration.py` | -| Integration tests | End-to-end workflows | `tests/integration/test_mcp_yourhost_integration.py` | - -### 1. Strategy Tests (Required) - -```python -import unittest -from pathlib import Path -from hatch.mcp_host_config import MCPHostRegistry, MCPHostType, MCPServerConfig, HostConfiguration -import hatch.mcp_host_config.strategies # Triggers registration - -class TestYourHostStrategy(unittest.TestCase): - def test_strategy_registration(self): - """Test that strategy is automatically registered.""" - strategy = MCPHostRegistry.get_strategy(MCPHostType.YOUR_HOST) - self.assertIsNotNone(strategy) - - def test_config_path(self): - """Test configuration path detection.""" - strategy = MCPHostRegistry.get_strategy(MCPHostType.YOUR_HOST) - self.assertIsNotNone(strategy.get_config_path()) - - def test_server_validation(self): - """Test server configuration validation.""" - strategy = MCPHostRegistry.get_strategy(MCPHostType.YOUR_HOST) - valid_config = MCPServerConfig(command="python", args=["server.py"]) - self.assertTrue(strategy.validate_server_config(valid_config)) -``` - -### 2. Backup Integration Tests (Required) - -```python -class TestYourHostBackupIntegration(unittest.TestCase): - def test_write_creates_backup(self): - """Test that write_configuration creates backup when no_backup=False.""" - # Setup temp config file - # Call write_configuration(config, no_backup=False) - # Verify backup file was created - - def test_write_skips_backup_when_requested(self): - """Test that write_configuration skips backup when no_backup=True.""" - # Call write_configuration(config, no_backup=True) - # Verify no backup file was created -``` - -### 3. Integration Testing - -```python -def test_configuration_manager_integration(self): - """Test integration with configuration manager.""" - manager = MCPHostConfigurationManager() - - server_config = MCPServerConfig( - name="test-server", - command="python", - args=["test.py"] - ) - - result = manager.configure_server( - server_config=server_config, - hostname="your-host", - no_backup=True # Skip backup for testing - ) - - self.assertTrue(result.success) - self.assertEqual(result.hostname, "your-host") - self.assertEqual(result.server_name, "test-server") -``` - -## Advanced Features - -### Custom Validation Rules - -Implement host-specific validation in `validate_server_config()`: - -```python -def validate_server_config(self, server_config: MCPServerConfig) -> bool: - """Custom validation for your host.""" - # Example: Your host doesn't support environment variables - if server_config.env: - logger.warning("Your host doesn't support environment variables") - return False - - # Example: Your host requires specific command format - if server_config.command and not server_config.command.endswith('.py'): - logger.warning("Your host only supports Python commands") - return False - - # Accept if it has either command or URL - return server_config.command is not None or server_config.url is not None -``` - -**Note:** Most hosts accept any command or URL. Only add restrictions if your host truly requires them. - -### Host-Specific Configuration Models - -Different hosts have different validation rules. The codebase provides host-specific models: - -- `MCPServerConfigClaude` - Claude Desktop/Code -- `MCPServerConfigCursor` - Cursor/LM Studio -- `MCPServerConfigVSCode` - VS Code -- `MCPServerConfigGemini` - Google Gemini -- `MCPServerConfigKiro` - Kiro IDE (with `disabled`, `autoApprove`, `disabledTools`) - -**When to create a host-specific model:** Only if your host has unique configuration fields not present in other hosts. - -**Implementation steps** (if needed): - -1. **Add model class** in `models.py`: -```python -class MCPServerConfigYourHost(MCPServerConfigBase): - your_field: Optional[str] = None - - @classmethod - def from_omni(cls, omni: "MCPServerConfigOmni") -> "MCPServerConfigYourHost": - return cls(**omni.model_dump(exclude_unset=True)) -``` - -2. **Register in `HOST_MODEL_REGISTRY`**: -```python -HOST_MODEL_REGISTRY = { - # ... existing entries ... - MCPHostType.YOUR_HOST: MCPServerConfigYourHost, -} -``` - -3. **Extend `MCPServerConfigOmni`** with your fields (for CLI integration) - -4. **Add CLI arguments** in `cli_hatch.py` (see next section) - -For most cases, the generic `MCPServerConfig` works fine - only add a host-specific model if truly needed. - -### CLI Integration for Host-Specific Fields - -If your host has unique configuration fields, extend the CLI to support them: - -1. **Update function signature** in `handle_mcp_configure()`: -```python -def handle_mcp_configure( - # ... existing params ... - your_field: Optional[str] = None, # Add your field -): -``` - -2. **Add argument parser entry**: -```python -configure_parser.add_argument( - '--your-field', - help='Description of your field' -) -``` - -3. **Update omni model population**: -```python -omni_config_data = { - # ... existing fields ... - 'your_field': your_field, -} -``` - -The conversion reporting system automatically handles new fields - no additional changes needed there. - -### Multi-File Configuration - -Some hosts split configuration across multiple files. Handle this in your read/write methods: - -```python -def read_configuration(self) -> HostConfiguration: - """Read from multiple configuration files.""" - servers = {} - - config_paths = [ - Path.home() / ".your_host" / "main.json", - Path.home() / ".your_host" / "servers.json" - ] - - for config_path in config_paths: - if config_path.exists(): - try: - with open(config_path, 'r') as f: - data = json.load(f) - # Merge server configurations - servers.update(data.get(self.get_config_key(), {})) - except Exception as e: - logger.warning(f"Failed to read {config_path}: {e}") - - # Convert to MCPServerConfig objects - result_servers = {} - for name, server_data in servers.items(): - try: - result_servers[name] = MCPServerConfig(**server_data) - except Exception as e: - logger.warning(f"Invalid server config for {name}: {e}") - - return HostConfiguration(servers=result_servers) - -def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write to primary configuration file.""" - # Write all servers to the main config file - primary_path = Path.home() / ".your_host" / "main.json" - - try: - primary_path.parent.mkdir(parents=True, exist_ok=True) - - existing_config = {} - if primary_path.exists(): - with open(primary_path, 'r') as f: - existing_config = json.load(f) - - servers_dict = { - name: server.model_dump(exclude_none=True) - for name, server in config.servers.items() - } - existing_config[self.get_config_key()] = servers_dict - - temp_path = primary_path.with_suffix('.tmp') - with open(temp_path, 'w') as f: - json.dump(existing_config, f, indent=2) - - temp_path.replace(primary_path) - return True - except Exception as e: - logger.error(f"Failed to write configuration: {e}") - return False -``` - -## Common Issues - -### Host Detection - -Implement robust host detection. The `is_host_available()` method is called by the CLI to determine which hosts are installed: - -```python -def is_host_available(self) -> bool: - """Check if host is available using multiple methods.""" - # Method 1: Check if config directory exists (most reliable) - config_path = self.get_config_path() - if config_path and config_path.parent.exists(): - return True - - # Method 2: Check if executable is in PATH - import shutil - if shutil.which("your-host-executable"): - return True - - # Method 3: Check for host-specific registry entries (Windows only) - if sys.platform == "win32": - try: - import winreg - with winreg.OpenKey(winreg.HKEY_CURRENT_USER, r"Software\YourHost"): - return True - except FileNotFoundError: - pass - - return False -``` - -**Example from codebase:** `ClaudeDesktopStrategy` checks if the config directory exists. - -### Error Handling in Read/Write - -Always wrap file I/O in try-catch and log errors: - -```python -def read_configuration(self) -> HostConfiguration: - """Read configuration with error handling.""" - config_path = self.get_config_path() - if not config_path or not config_path.exists(): - return HostConfiguration() # Return empty config, don't fail - - try: - with open(config_path, 'r') as f: - config_data = json.load(f) - # ... process config_data ... - return HostConfiguration(servers=servers) - except json.JSONDecodeError as e: - logger.error(f"Invalid JSON in {config_path}: {e}") - return HostConfiguration() # Graceful fallback - except Exception as e: - logger.error(f"Failed to read configuration: {e}") - return HostConfiguration() # Graceful fallback -``` - -### Atomic Writes Prevent Corruption - -Always use atomic writes to prevent config file corruption on failure: - -```python -def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write configuration atomically.""" - config_path = self.get_config_path() - if not config_path: - return False - - try: - config_path.parent.mkdir(parents=True, exist_ok=True) - - # Read existing config - existing_config = {} - if config_path.exists(): - try: - with open(config_path, 'r') as f: - existing_config = json.load(f) - except Exception: - pass - - # Prepare new config - servers_dict = { - name: server.model_dump(exclude_none=True) - for name, server in config.servers.items() - } - existing_config[self.get_config_key()] = servers_dict - - # Write to temp file first - temp_path = config_path.with_suffix('.tmp') - with open(temp_path, 'w') as f: - json.dump(existing_config, f, indent=2) - - # Atomic replace - if this fails, original file is untouched - temp_path.replace(config_path) - return True - - except Exception as e: - logger.error(f"Failed to write configuration: {e}") - return False -``` - -**Why atomic writes matter:** If the process crashes during `write()`, the original config file remains intact. The temp file approach ensures either the old config or the new config exists, never a corrupted partial write. - -### Preserving Non-MCP Settings - -Always read existing config first and only update the MCP servers section: - -```python -# Read existing config -existing_config = {} -if config_path.exists(): - with open(config_path, 'r') as f: - existing_config = json.load(f) - -# Update only MCP servers, preserve everything else -existing_config[self.get_config_key()] = servers_dict - -# Write back -with open(temp_path, 'w') as f: - json.dump(existing_config, f, indent=2) -``` - -This ensures your strategy doesn't overwrite other settings the host application manages. - -## Integration with Hatch CLI - -Your strategy will automatically work with Hatch CLI commands once registered and imported: - -```bash -# Discover available hosts (including your new host if installed) -hatch mcp discover hosts - -# Configure server on your host -hatch mcp configure my-server --host your-host - -# List servers on your host -hatch mcp list --host your-host - -# Remove server from your host -hatch mcp remove my-server --host your-host -``` - -**Important:** For CLI discovery to work, your strategy module must be imported. This happens automatically when: -1. The strategy is in `hatch/mcp_host_config/strategies.py`, or -2. The CLI imports `hatch.mcp_host_config.strategies` (which it does) - -The CLI automatically discovers your strategy through the `@register_host_strategy` decorator registration system. - -## Implementation Summary - -After completing your implementation, verify all integration points: - -- [ ] Host type added to `MCPHostType` enum -- [ ] Strategy class implemented with `@register_host_strategy` decorator -- [ ] Backup integration working (test with `no_backup=False` and `no_backup=True`) -- [ ] Host-specific model created (if needed) and registered in `HOST_MODEL_REGISTRY` -- [ ] CLI arguments added (if needed) with omni model population -- [ ] All test categories implemented and passing -- [ ] Strategy exported from `__init__.py` (if in separate file) +# Extending MCP Host Configuration + +**Quick Start:** Create an adapter (validation + serialization), create a strategy (file I/O), add tests. Most implementations are 50-100 lines per file. + +## Before You Start: Integration Checklist + +The Unified Adapter Architecture requires only **4 integration points**: + +| Integration Point | Required? | Files to Modify | +|-------------------|-----------|-----------------| +| ☐ Host type enum | Always | `models.py` | +| ☐ Adapter class | Always | `adapters/your_host.py`, `adapters/__init__.py` | +| ☐ Strategy class | Always | `strategies.py` | +| ☐ Test infrastructure | Always | `tests/unit/mcp/`, `tests/integration/mcp/` | + +> **Note:** No host-specific models, no `from_omni()` conversion, no model registry integration. The unified model handles all fields. + +## When You Need This + +You want Hatch to configure MCP servers on a new host platform: + +- A code editor not yet supported (Zed, Neovim, etc.) +- A custom MCP host implementation +- Cloud-based development environments +- Specialized MCP server platforms + +## The Pattern: Adapter + Strategy + +The Unified Adapter Architecture separates concerns: + +| Component | Responsibility | Interface | +|-----------|----------------|-----------| +| **Adapter** | Validation + Serialization | `validate()`, `serialize()`, `get_supported_fields()` | +| **Strategy** | File I/O | `read_configuration()`, `write_configuration()`, `get_config_path()` | + +``` +MCPServerConfig (unified model) + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Adapter β”‚ ← Validates fields, serializes to host format +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Strategy β”‚ ← Reads/writes configuration files +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + config.json +``` + +## Implementation Steps + +### Step 1: Add Host Type Enum + +Add your host to `MCPHostType` in `hatch/mcp_host_config/models.py`: + +```python +class MCPHostType(str, Enum): + # ... existing types ... + YOUR_HOST = "your-host" # Use lowercase with hyphens +``` + +### Step 2: Create Host Adapter + +Create `hatch/mcp_host_config/adapters/your_host.py`: + +```python +"""Your Host adapter for MCP host configuration.""" + +from typing import Any, Dict, FrozenSet + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.fields import UNIVERSAL_FIELDS +from hatch.mcp_host_config.models import MCPServerConfig + + +class YourHostAdapter(BaseAdapter): + """Adapter for Your Host.""" + + @property + def host_name(self) -> str: + return "your-host" + + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields Your Host accepts.""" + # Start with universal fields, add host-specific ones + return UNIVERSAL_FIELDS | frozenset({ + "type", # If your host supports transport type + # "your_specific_field", + }) + + def validate(self, config: MCPServerConfig) -> None: + """Validate configuration for Your Host.""" + # Check transport requirements + if not config.command and not config.url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) required", + host_name=self.host_name + ) + + # Add any host-specific validation + # if config.command and config.url: + # raise AdapterValidationError("Cannot have both", ...) + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize configuration for Your Host format.""" + self.validate(config) + return self.filter_fields(config) +``` + +**Then register in `hatch/mcp_host_config/adapters/__init__.py`:** + +```python +from hatch.mcp_host_config.adapters.your_host import YourHostAdapter + +__all__ = [ + # ... existing exports ... + "YourHostAdapter", +] +``` + +**And add to registry in `hatch/mcp_host_config/adapters/registry.py`:** + +```python +from hatch.mcp_host_config.adapters.your_host import YourHostAdapter + +def _register_defaults(self) -> None: + # ... existing registrations ... + self.register(YourHostAdapter()) +``` + +### Step 3: Create Host Strategy + +Add to `hatch/mcp_host_config/strategies.py`: + +```python +@register_host_strategy(MCPHostType.YOUR_HOST) +class YourHostStrategy(MCPHostStrategy): + """Strategy for Your Host file I/O.""" + + def get_config_path(self) -> Optional[Path]: + """Return path to config file.""" + return Path.home() / ".your_host" / "config.json" + + def is_host_available(self) -> bool: + """Check if host is installed.""" + config_path = self.get_config_path() + return config_path is not None and config_path.parent.exists() + + def get_config_key(self) -> str: + """Return the key containing MCP servers.""" + return "mcpServers" # Most hosts use this + + # read_configuration() and write_configuration() + # can inherit from a base class or implement from scratch +``` + +**Inheriting from existing strategy families:** + +```python +# If similar to Claude (standard JSON format) +class YourHostStrategy(ClaudeHostStrategy): + def get_config_path(self) -> Optional[Path]: + return Path.home() / ".your_host" / "config.json" + +# If similar to Cursor (flexible path handling) +class YourHostStrategy(CursorBasedHostStrategy): + def get_config_path(self) -> Optional[Path]: + return Path.home() / ".your_host" / "config.json" +``` + +### Step 4: Add Tests + +**Unit tests** (`tests/unit/mcp/test_your_host_adapter.py`): + +```python +class TestYourHostAdapter(unittest.TestCase): + def setUp(self): + self.adapter = YourHostAdapter() + + def test_host_name(self): + self.assertEqual(self.adapter.host_name, "your-host") + + def test_supported_fields(self): + fields = self.adapter.get_supported_fields() + self.assertIn("command", fields) + + def test_validate_requires_transport(self): + config = MCPServerConfig(name="test") + with self.assertRaises(AdapterValidationError): + self.adapter.validate(config) + + def test_serialize_filters_unsupported(self): + config = MCPServerConfig(name="test", command="python", httpUrl="http://x") + result = self.adapter.serialize(config) + self.assertNotIn("httpUrl", result) # Assuming not supported +``` + +## Declaring Field Support + +### Using Field Constants + +Import from `hatch/mcp_host_config/fields.py`: + +```python +from hatch.mcp_host_config.fields import ( + UNIVERSAL_FIELDS, # command, args, env, url, headers + CLAUDE_FIELDS, # UNIVERSAL + type + VSCODE_FIELDS, # CLAUDE + envFile, inputs + CURSOR_FIELDS, # CLAUDE + envFile +) + +# Compose your host's fields +YOUR_HOST_FIELDS = UNIVERSAL_FIELDS | frozenset({ + "type", + "your_specific_field", +}) +``` + +### Adding New Host-Specific Fields + +If your host has unique fields not in the unified model: + +1. **Add to `MCPServerConfig`** in `models.py`: + +```python +# Host-specific fields +your_field: Optional[str] = Field(None, description="Your Host specific field") +``` + +2. **Add to field constants** in `fields.py`: + +```python +YOUR_HOST_FIELDS = UNIVERSAL_FIELDS | frozenset({ + "your_field", +}) +``` + +3. **Add CLI argument** (optional) in `hatch/cli/__main__.py`: + +```python +mcp_configure_parser.add_argument( + "--your-field", + help="Your Host specific field" +) +``` + +## Field Mappings (Optional) + +If your host uses different names for standard fields: + +```python +# In your adapter +def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + self.validate(config) + result = self.filter_fields(config) + + # Apply mappings (e.g., 'args' β†’ 'arguments') + if "args" in result: + result["arguments"] = result.pop("args") + + return result +``` + +Or define mappings centrally in `fields.py`: + +```python +YOUR_HOST_FIELD_MAPPINGS = { + "args": "arguments", + "headers": "http_headers", +} +``` + +## Common Patterns + +### Multiple Transport Support + +Some hosts (like Gemini) support multiple transports: + +```python +def validate(self, config: MCPServerConfig) -> None: + transports = sum([ + config.command is not None, + config.url is not None, + config.httpUrl is not None, + ]) + + if transports == 0: + raise AdapterValidationError("At least one transport required") + + # Allow multiple transports if your host supports it +``` + +### Strict Single Transport + +Some hosts (like Claude) require exactly one transport: + +```python +def validate(self, config: MCPServerConfig) -> None: + has_command = config.command is not None + has_url = config.url is not None + + if not has_command and not has_url: + raise AdapterValidationError("Need command or url") + + if has_command and has_url: + raise AdapterValidationError("Cannot have both command and url") +``` + +### Custom Serialization + +Override `serialize()` for custom output format: + +```python +def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + self.validate(config) + result = self.filter_fields(config) + + # Transform to your host's expected structure + if config.type == "stdio": + result["transport"] = {"type": "stdio", "command": result.pop("command")} + + return result +``` + +## Testing Your Implementation + +### Test Categories + +| Category | What to Test | +|----------|--------------| +| **Protocol** | `host_name`, `get_supported_fields()` return correct values | +| **Validation** | `validate()` accepts valid configs, rejects invalid | +| **Serialization** | `serialize()` produces correct format, filters fields | +| **Integration** | Adapter works with registry, strategy reads/writes files | + +### Test File Location + +``` +tests/ +β”œβ”€β”€ unit/mcp/ +β”‚ └── test_your_host_adapter.py # Protocol + validation + serialization +└── integration/mcp/ + └── test_your_host_strategy.py # File I/O + end-to-end +``` + +## Troubleshooting + +### Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| Adapter not found | Not registered in registry | Add to `_register_defaults()` | +| Field not serialized | Not in `get_supported_fields()` | Add field to set | +| Validation always fails | Logic error in `validate()` | Check conditions | +| Name appears in output | Not filtering excluded fields | Use `filter_fields()` | + +### Debugging Tips + +```python +# Print what adapter sees +adapter = get_adapter("your-host") +print(f"Supported fields: {adapter.get_supported_fields()}") + +config = MCPServerConfig(name="test", command="python") +print(f"Filtered: {adapter.filter_fields(config)}") +print(f"Serialized: {adapter.serialize(config)}") +``` + +## Reference: Existing Adapters + +Study these for patterns: + +| Adapter | Notable Features | +|---------|------------------| +| `ClaudeAdapter` | Variant support (desktop/code), strict transport validation | +| `VSCodeAdapter` | Extended fields (envFile, inputs) | +| `GeminiAdapter` | Multiple transport support, many host-specific fields | +| `KiroAdapter` | Disabled/autoApprove fields | +| `CodexAdapter` | Field mappings (argsβ†’arguments) | + +## Summary + +Adding a new host is now a **4-step process**: + +1. **Add enum** to `MCPHostType` +2. **Create adapter** with `validate()` + `serialize()` + `get_supported_fields()` +3. **Create strategy** with `get_config_path()` + file I/O methods +4. **Add tests** for adapter and strategy + +The unified model handles all fields. Adapters filter and validate. Strategies handle files. No model conversion needed. diff --git a/docs/articles/devs/implementation_guides/package_loader_extensions.md b/docs/articles/devs/implementation_guides/package_loader_extensions.md index 1c027a1..9c4e1b2 100644 --- a/docs/articles/devs/implementation_guides/package_loader_extensions.md +++ b/docs/articles/devs/implementation_guides/package_loader_extensions.md @@ -38,9 +38,9 @@ class MultiFormatLoader(HatchPackageLoader): if metadata_file.exists(): metadata = self._load_by_format(metadata_file) return self.validate_and_parse(metadata, package_path) - + raise PackageLoadError("No supported metadata file found") - + def _load_by_format(self, file_path: Path) -> Dict: if file_path.suffix == ".json": return json.load(file_path.open()) @@ -56,13 +56,13 @@ class ValidatingLoader(HatchPackageLoader): def validate_and_parse(self, metadata: Dict, package_path: Path) -> PackageMetadata: # Run standard validation first result = super().validate_and_parse(metadata, package_path) - + # Add custom validation self._validate_entry_points_exist(metadata, package_path) self._validate_license_file_exists(metadata, package_path) - + return result - + def _validate_entry_points_exist(self, metadata: Dict, package_path: Path): entry_point = metadata.get("entry_point") if entry_point and not (package_path / entry_point).exists(): @@ -76,13 +76,13 @@ class EnvironmentLoader(HatchPackageLoader): def __init__(self, target_env="production"): super().__init__() self.target_env = target_env - + def validate_and_parse(self, metadata: Dict, package_path: Path) -> PackageMetadata: # Transform metadata for target environment if self.target_env == "production": # Remove development dependencies metadata.get("dependencies", {}).pop("development", None) - + return super().validate_and_parse(metadata, package_path) ``` @@ -113,12 +113,12 @@ class SchemaValidatingLoader(HatchPackageLoader): def __init__(self, external_validator): super().__init__() self.external_validator = external_validator - + def validate_and_parse(self, metadata: Dict, package_path: Path) -> PackageMetadata: # Use external validation service if not self.external_validator.validate(metadata): raise ValidationError("External validation failed") - + return super().validate_and_parse(metadata, package_path) ``` @@ -156,51 +156,51 @@ Check existing code for patterns: ```python class EnhancedPackageValidator: """Enhanced package validator with custom rules.""" - + def __init__(self, base_validator): self.base_validator = base_validator self.custom_validators = [] - + def add_custom_validator(self, validator_func): """Add custom validation function.""" self.custom_validators.append(validator_func) - + def validate_package(self, metadata: Dict[str, Any], package_path: Path) -> ValidationResult: """Validate package with base and custom validators.""" # Run base schema validation base_result = self.base_validator.validate(metadata) - + if not base_result.is_valid: return base_result - + # Run custom validators for validator in self.custom_validators: custom_result = validator(metadata, package_path) if not custom_result.is_valid: return custom_result - + return ValidationResult(is_valid=True) # Example custom validators def validate_entry_points_exist(metadata: Dict[str, Any], package_path: Path) -> ValidationResult: """Validate that entry point files actually exist.""" entry_points = metadata.get("entry_points", {}) - + for entry_point_name, entry_point_path in entry_points.items(): full_path = package_path / entry_point_path - + if not full_path.exists(): return ValidationResult( is_valid=False, error_message=f"Entry point file not found: {entry_point_path}" ) - + return ValidationResult(is_valid=True) def validate_dependency_versions(metadata: Dict[str, Any], package_path: Path) -> ValidationResult: """Validate dependency version specifications.""" dependencies = metadata.get("dependencies", {}) - + for dep_type, dep_list in dependencies.items(): for dependency in dep_list: version = dependency.get("version") @@ -209,7 +209,7 @@ def validate_dependency_versions(metadata: Dict[str, Any], package_path: Path) - is_valid=False, error_message=f"Invalid version specification: {version}" ) - + return ValidationResult(is_valid=True) ``` @@ -220,39 +220,39 @@ Extend metadata processing for specialized use cases: ```python class MetadataProcessor: """Process and transform package metadata.""" - + def __init__(self): self.processors = [] - + def add_processor(self, processor_func): """Add metadata processing function.""" self.processors.append(processor_func) - + def process_metadata(self, metadata: Dict[str, Any]) -> Dict[str, Any]: """Apply all processors to metadata.""" processed_metadata = metadata.copy() - + for processor in self.processors: processed_metadata = processor(processed_metadata) - + return processed_metadata # Example processors def normalize_dependency_versions(metadata: Dict[str, Any]) -> Dict[str, Any]: """Normalize dependency version specifications.""" dependencies = metadata.get("dependencies", {}) - + for dep_type, dep_list in dependencies.items(): for dependency in dep_list: if "version" in dependency: dependency["version"] = _normalize_version_spec(dependency["version"]) - + return metadata def resolve_template_variables(metadata: Dict[str, Any]) -> Dict[str, Any]: """Resolve template variables in metadata.""" template_vars = metadata.get("template_vars", {}) - + def replace_vars(obj): if isinstance(obj, str): for var_name, var_value in template_vars.items(): @@ -263,7 +263,7 @@ def resolve_template_variables(metadata: Dict[str, Any]) -> Dict[str, Any]: elif isinstance(obj, list): return [replace_vars(item) for item in obj] return obj - + return replace_vars(metadata) ``` @@ -276,35 +276,35 @@ Implement lazy loading and caching for performance: ```python class CachedPackageLoader(HatchPackageLoader): """Package loader with caching support.""" - + def __init__(self, cache_ttl=3600): super().__init__() self.cache = {} self.cache_ttl = cache_ttl - + def load_package(self, package_path: Path) -> PackageMetadata: """Load package with caching.""" cache_key = str(package_path.resolve()) - + # Check cache if cache_key in self.cache: cached_entry = self.cache[cache_key] if not self._is_cache_expired(cached_entry): return cached_entry["metadata"] - + # Load and cache metadata = super().load_package(package_path) self.cache[cache_key] = { "metadata": metadata, "timestamp": time.time() } - + return metadata - + def _is_cache_expired(self, cache_entry: Dict[str, Any]) -> bool: """Check if cache entry has expired.""" return time.time() - cache_entry["timestamp"] > self.cache_ttl - + def invalidate_cache(self, package_path: Path = None): """Invalidate cache for specific package or all packages.""" if package_path: @@ -321,46 +321,46 @@ Implement dependency resolution during package loading: ```python class DependencyResolvingLoader(HatchPackageLoader): """Package loader with dependency resolution.""" - + def __init__(self, registry_retriever): super().__init__() self.registry_retriever = registry_retriever - + def load_package_with_dependencies(self, package_path: Path) -> PackageWithDependencies: """Load package and resolve its dependencies.""" metadata = self.load_package(package_path) - + resolved_dependencies = self._resolve_dependencies(metadata.dependencies) - + return PackageWithDependencies( metadata=metadata, resolved_dependencies=resolved_dependencies ) - + def _resolve_dependencies(self, dependencies: Dict[str, List[Dict]]) -> Dict[str, List[ResolvedDependency]]: """Resolve dependency specifications to concrete versions.""" resolved = {} - + for dep_type, dep_list in dependencies.items(): resolved[dep_type] = [] - + for dependency in dep_list: resolved_dep = self._resolve_single_dependency(dependency) resolved[dep_type].append(resolved_dep) - + return resolved - + def _resolve_single_dependency(self, dependency: Dict[str, Any]) -> ResolvedDependency: """Resolve a single dependency specification.""" name = dependency["name"] version_spec = dependency.get("version", "latest") - + # Query registry for available versions available_versions = self.registry_retriever.get_package_versions(name) - + # Resolve version specification resolved_version = self._resolve_version_spec(version_spec, available_versions) - + return ResolvedDependency( name=name, requested_version=version_spec, @@ -376,19 +376,19 @@ Transform packages for different environments or use cases: ```python class PackageTransformer: """Transform packages for different environments.""" - + def __init__(self): self.transformers = {} - + def register_transformer(self, target_env: str, transformer_func): """Register transformer for specific environment.""" self.transformers[target_env] = transformer_func - + def transform_package(self, metadata: PackageMetadata, target_env: str) -> PackageMetadata: """Transform package for target environment.""" if target_env not in self.transformers: return metadata # No transformation needed - + transformer = self.transformers[target_env] return transformer(metadata) @@ -399,11 +399,11 @@ def transform_for_production(metadata: PackageMetadata) -> PackageMetadata: if "dependencies" in metadata.raw_data: dependencies = metadata.raw_data["dependencies"] dependencies.pop("development", None) - + # Set production-specific configuration metadata.raw_data["environment"] = "production" metadata.raw_data["debug"] = False - + return PackageMetadata(metadata.raw_data) def transform_for_testing(metadata: PackageMetadata) -> PackageMetadata: @@ -413,12 +413,12 @@ def transform_for_testing(metadata: PackageMetadata) -> PackageMetadata: {"name": "pytest", "version": ">=6.0.0"}, {"name": "pytest-mock", "version": ">=3.0.0"} ] - + if "dependencies" not in metadata.raw_data: metadata.raw_data["dependencies"] = {} - + metadata.raw_data["dependencies"]["testing"] = test_deps - + return PackageMetadata(metadata.raw_data) ``` @@ -431,38 +431,38 @@ Work with external schema validation: ```python class SchemaAwareLoader(HatchPackageLoader): """Package loader with schema version management.""" - + def __init__(self, schema_manager): super().__init__() self.schema_manager = schema_manager - + def load_package(self, package_path: Path) -> PackageMetadata: """Load package with appropriate schema validation.""" metadata = self._load_raw_metadata(package_path) - + # Determine schema version schema_version = self._determine_schema_version(metadata) - + # Get appropriate schema schema = self.schema_manager.get_schema(schema_version) - + # Validate against schema validation_result = schema.validate(metadata) if not validation_result.is_valid: raise ValidationError(f"Schema validation failed: {validation_result.errors}") - + return self.parse_metadata(metadata, package_path) - + def _determine_schema_version(self, metadata: Dict[str, Any]) -> str: """Determine appropriate schema version for metadata.""" # Check explicit schema version if "schema_version" in metadata: return metadata["schema_version"] - + # Infer from metadata structure if "hatch_version" in metadata: return self._map_hatch_version_to_schema(metadata["hatch_version"]) - + # Default to latest return "latest" ``` @@ -476,26 +476,26 @@ class TestCustomPackageLoader: def test_yaml_metadata_loading(self): """Test loading YAML metadata files.""" loader = CustomPackageLoader() - + # Create test package with YAML metadata test_package_path = self._create_test_package_yaml() - + metadata = loader.load_package(test_package_path) - + assert metadata.name == "test-package" assert metadata.version == "1.0.0" - + def test_custom_validation_rules(self): """Test custom validation rules.""" validator = EnhancedPackageValidator(base_validator) validator.add_custom_validator(validate_entry_points_exist) - + # Test with missing entry point file metadata = {"entry_points": {"main": "nonexistent.py"}} package_path = Path("/tmp/test-package") - + result = validator.validate_package(metadata, package_path) - + assert not result.is_valid assert "Entry point file not found" in result.error_message ``` @@ -507,11 +507,11 @@ def test_package_loading_with_registry_integration(): """Test package loading with registry dependency resolution.""" registry_retriever = MockRegistryRetriever() loader = DependencyResolvingLoader(registry_retriever) - + package_path = create_test_package_with_dependencies() - + package_with_deps = loader.load_package_with_dependencies(package_path) - + assert len(package_with_deps.resolved_dependencies["python"]) > 0 assert all(dep.resolved_version for dep in package_with_deps.resolved_dependencies["python"]) ``` diff --git a/docs/articles/devs/implementation_guides/registry_integration.md b/docs/articles/devs/implementation_guides/registry_integration.md index f24f879..868bf7d 100644 --- a/docs/articles/devs/implementation_guides/registry_integration.md +++ b/docs/articles/devs/implementation_guides/registry_integration.md @@ -36,22 +36,22 @@ class PrivateRegistryRetriever(RegistryRetriever): super().__init__() self.base_url = base_url self.api_key = api_key - + def download_package(self, package_name: str, version: str, target_dir: Path) -> Path: headers = {"Authorization": f"Bearer {self.api_key}"} download_url = f"{self.base_url}/packages/{package_name}/{version}/download" - + response = requests.get(download_url, headers=headers) response.raise_for_status() - + package_file = target_dir / f"{package_name}-{version}.zip" package_file.write_bytes(response.content) return package_file - + def get_package_versions(self, package_name: str) -> List[str]: headers = {"Authorization": f"Bearer {self.api_key}"} url = f"{self.base_url}/packages/{package_name}/versions" - + response = requests.get(url, headers=headers) response.raise_for_status() return response.json()["versions"] @@ -64,22 +64,22 @@ class LocalRegistryRetriever(RegistryRetriever): def __init__(self, registry_path: Path): super().__init__() self.registry_path = registry_path - + def download_package(self, package_name: str, version: str, target_dir: Path) -> Path: source_path = self.registry_path / package_name / version if not source_path.exists(): raise PackageNotFoundError(f"Package {package_name}=={version} not found locally") - + # Copy to target directory package_dir = target_dir / f"{package_name}-{version}" shutil.copytree(source_path, package_dir) return package_dir - + def get_package_versions(self, package_name: str) -> List[str]: package_path = self.registry_path / package_name if not package_path.exists(): return [] - + return [d.name for d in package_path.iterdir() if d.is_dir()] ``` @@ -92,17 +92,17 @@ class CachedRegistryRetriever(RegistryRetriever): self.upstream = upstream_retriever self.cache_dir = cache_dir self.cache_dir.mkdir(parents=True, exist_ok=True) - + def download_package(self, package_name: str, version: str, target_dir: Path) -> Path: cache_key = f"{package_name}-{version}" cached_path = self.cache_dir / cache_key - + if cached_path.exists(): # Copy from cache target_path = target_dir / cache_key shutil.copytree(cached_path, target_path) return target_path - + # Download and cache package_path = self.upstream.download_package(package_name, version, target_dir) shutil.copytree(package_path, cached_path) @@ -116,16 +116,16 @@ class FallbackRegistryRetriever(RegistryRetriever): def __init__(self, retrievers: List[RegistryRetriever]): super().__init__() self.retrievers = retrievers - + def download_package(self, package_name: str, version: str, target_dir: Path) -> Path: for retriever in self.retrievers: try: return retriever.download_package(package_name, version, target_dir) except PackageNotFoundError: continue - + raise PackageNotFoundError(f"Package {package_name}=={version} not found in any registry") - + def get_package_versions(self, package_name: str) -> List[str]: all_versions = set() for retriever in self.retrievers: @@ -134,7 +134,7 @@ class FallbackRegistryRetriever(RegistryRetriever): all_versions.update(versions) except Exception: continue - + return sorted(all_versions) ``` @@ -174,7 +174,7 @@ class ConfigurableRegistryRetriever(RegistryRetriever): self.config = config self.base_url = config["base_url"] self.timeout = config.get("timeout", 30) - + @classmethod def from_config_file(cls, config_path: Path): with open(config_path) as f: @@ -193,10 +193,10 @@ class TestPrivateRegistry(unittest.TestCase): mock_response = Mock() mock_response.content = b"fake package data" mock_get.return_value = mock_response - + registry = PrivateRegistryRetriever("https://example.com", "fake-key") package_path = registry.download_package("test-pkg", "1.0.0", Path("/tmp")) - + self.assertTrue(package_path.exists()) mock_get.assert_called_with( "https://example.com/packages/test-pkg/1.0.0/download", diff --git a/docs/articles/users/CLIReference.md b/docs/articles/users/CLIReference.md index fbbc0d5..4eb6951 100644 --- a/docs/articles/users/CLIReference.md +++ b/docs/articles/users/CLIReference.md @@ -1,6 +1,6 @@ # CLI Reference -This document is a compact reference of all Hatch CLI commands and options implemented in `hatch/cli_hatch.py` presented as tables for quick lookup. +This document is a compact reference of all Hatch CLI commands and options implemented in the `hatch/cli/` package, presented as tables for quick lookup. ## Table of Contents @@ -135,11 +135,136 @@ Syntax: #### `hatch env list` +List all environments with package counts. + +Syntax: + +`hatch env list [--pattern PATTERN] [--json]` + +| Flag | Type | Description | Default | +|---:|---|---|---| +| `--pattern` | string | Filter environments by name using regex pattern | none | +| `--json` | flag | Output in JSON format | false | + +**Example Output**: + +```bash +$ hatch env list +Environments: + Name Python Packages + ─────────────────────────────────────── + * default 3.14.2 0 + test-env 3.11.5 3 +``` + +**Key Details**: +- Header: `"Environments:"` only +- Columns: Name (width 15), Python (width 10), Packages (width 10, right-aligned) +- Current environment marked with `"* "` prefix +- Packages column shows COUNT only +- Separator: `"─"` character (U+2500) + +#### `hatch env list hosts` + +List environment/host/server deployments from environment data. + +Syntax: + +`hatch env list hosts [--env PATTERN] [--server PATTERN] [--json]` + +| Flag | Type | Description | Default | +|---:|---|---|---| +| `--env`, `-e` | string | Filter by environment name using regex pattern | none | +| `--server` | string | Filter by server name using regex pattern | none | +| `--json` | flag | Output in JSON format | false | + +**Example Output**: + +```bash +$ hatch env list hosts +Environment Host Deployments: + Environment Host Server Version + ───────────────────────────────────────────────────────────────── + default claude-desktop weather-server 1.0.0 + default cursor weather-server 1.0.0 +``` + +**Description**: +Lists environment/host/server deployments from environment data. Shows only Hatch-managed packages and their host deployments. + +#### `hatch env list servers` + +List environment/server/host deployments from environment data. + +Syntax: + +`hatch env list servers [--env PATTERN] [--host PATTERN] [--json]` + +| Flag | Type | Description | Default | +|---:|---|---|---| +| `--env`, `-e` | string | Filter by environment name using regex pattern | none | +| `--host` | string | Filter by host name using regex pattern (use '-' for undeployed) | none | +| `--json` | flag | Output in JSON format | false | + +**Example Output**: + +```bash +$ hatch env list servers +Environment Servers: + Environment Server Host Version + ───────────────────────────────────────────────────────────────── + default weather-server claude-desktop 1.0.0 + default weather-server cursor 1.0.0 + test-env utility-pkg - 2.1.0 +``` + +**Description**: +Lists environment/server/host deployments from environment data. Shows only Hatch-managed packages. Undeployed packages show '-' in Host column. + +#### `hatch env show` + +Display detailed hierarchical view of a specific environment. + Syntax: -`hatch env list` +`hatch env show ` + +| Argument | Type | Description | +|---:|---|---| +| `name` | string (positional) | Environment name to show (required) | + +**Example Output**: + +```bash +$ hatch env show default +Environment: default (active) + Description: My development environment + Created: 2026-01-15 10:30:00 + + Python Environment: + Version: 3.14.2 + Executable: /path/to/python + Conda env: N/A + Status: Active + + Packages (2): + weather-server + Version: 1.0.0 + Source: registry (https://registry.example.com) + Deployed to: claude-desktop, cursor + + utility-pkg + Version: 2.1.0 + Source: local (/path/to/package) + Deployed to: (none) +``` -Description: Lists all environments. When a Python manager (conda/mamba) is available additional status and manager info are displayed. +**Key Details**: +- Header shows `"(active)"` suffix if current environment +- Hierarchical structure with 2-space indentation +- No separator lines between sections +- Packages section shows count in header +- Each package shows version, source, and deployed hosts #### `hatch env use` @@ -300,6 +425,8 @@ Syntax: #### `hatch package list` +**⚠️ DEPRECATED**: This command is deprecated. Use `hatch env list` to see packages inline with environment information, or `hatch env show ` for detailed package information. + List packages installed in a Hatch environment. Syntax: @@ -310,7 +437,19 @@ Syntax: |---:|---|---|---| | `--env`, `-e` | string | Hatch environment name (defaults to current) | current environment | -Output: each package row includes name, version, hatch compliance flag, source URI and installation location. +**Example Output**: + +```bash +$ hatch package list +Warning: 'hatch package list' is deprecated. Use 'hatch env list' instead, which shows packages inline. +Packages in environment 'default': +weather-server (1.0.0) Hatch compliant: True source: https://registry.example.com location: /path/to/package +``` + +**Migration Guide**: +- For package counts: Use `hatch env list` (shows package count per environment) +- For detailed package info: Use `hatch env show ` (shows full package details) +- For deployment info: Use `hatch env list hosts` or `hatch env list servers` #### `hatch package sync` @@ -434,17 +573,17 @@ The conversion report shows: - **UNSUPPORTED** fields: Fields not supported by the target host (automatically filtered out) - **UNCHANGED** fields: Fields that already have the specified value (update operations only) +Note: Internal metadata fields (like `name`) are not shown in the field operations list, as they are used for internal bookkeeping and are not written to host configuration files. The server name is displayed in the report header for context. + **Example - Local Server Configuration**: ```bash $ hatch mcp configure my-server --host claude-desktop --command python --args server.py --env API_KEY=secret Server 'my-server' created for host 'claude-desktop': - name: UPDATED None --> 'my-server' command: UPDATED None --> 'python' args: UPDATED None --> ['server.py'] env: UPDATED None --> {'API_KEY': 'secret'} - url: UPDATED None --> None Configure MCP server 'my-server' on host 'claude-desktop'? [y/N]: y [SUCCESS] Successfully configured MCP server 'my-server' on host 'claude-desktop' @@ -575,11 +714,8 @@ $ hatch mcp configure my-server --host gemini --command python --args server.py [DRY RUN] Args: ['server.py'] [DRY RUN] Backup: Enabled [DRY RUN] Preview of changes for server 'my-server': - name: UPDATED None --> 'my-server' command: UPDATED None --> 'python' args: UPDATED None --> ['server.py'] - env: UPDATED None --> {} - url: UPDATED None --> None No changes were made. ``` @@ -600,6 +736,8 @@ When configuring a server with fields not supported by the target host, those fi Synchronize MCP configurations across environments and hosts. +The sync command displays a preview of servers to be synced before requesting confirmation, giving visibility into which servers will be affected. + Syntax: `hatch mcp sync [--from-env ENV | --from-host HOST] --to-host HOSTS [--servers SERVERS | --pattern PATTERN] [--dry-run] [--auto-approve] [--no-backup]` @@ -615,6 +753,27 @@ Syntax: | `--auto-approve` | flag | Skip confirmation prompts | false | | `--no-backup` | flag | Skip backup creation before synchronization | false | +**Example Output (pre-prompt)**: + +``` +hatch mcp sync: + [INFO] Servers: weather-server, my-tool (2 total) + [SYNC] environment 'dev' β†’ 'claude-desktop' + [SYNC] environment 'dev' β†’ 'cursor' + Proceed? [y/N]: +``` + +When more than 3 servers match, the list is truncated: `Servers: srv1, srv2, srv3, ... (7 total)` + +**Error Output**: + +Sync failures use standardized error formatting with structured details: + +``` +[ERROR] Synchronization failed + claude-desktop: Config file not found +``` + #### `hatch mcp remove server` Remove an MCP server from one or more hosts. @@ -649,78 +808,190 @@ Syntax: #### `hatch mcp list hosts` -List MCP hosts configured in the current environment. +List host/server pairs from host configuration files. -**Purpose**: Shows hosts that have MCP servers configured in the specified environment, with package-level details. +**Purpose**: Shows ALL servers on hosts (both Hatch-managed and third-party) with Hatch management status. Syntax: -`hatch mcp list hosts [--env ENV] [--detailed]` +`hatch mcp list hosts [--server PATTERN] [--json]` | Flag | Type | Description | Default | |---:|---|---|---| -| `--env` | string | Environment to list hosts from | current environment | -| `--detailed` | flag | Show detailed configuration information | false | +| `--server` | string | Filter by server name using regex pattern | none | +| `--json` | flag | Output in JSON format | false | **Example Output**: -```text -Configured hosts for environment 'my-project': - claude-desktop (2 packages) - cursor (1 package) +```bash +$ hatch mcp list hosts +MCP Hosts: + Host Server Hatch Environment + ───────────────────────────────────────────────────────────────── + claude-desktop weather-server βœ… default + claude-desktop third-party-tool ❌ - + cursor weather-server βœ… default ``` -**Detailed Output** (`--detailed`): +**Key Details**: +- Header: `"MCP Hosts:"` +- Columns: Host (width 18), Server (width 18), Hatch (width 8), Environment (width 15) +- Hatch column: `"βœ…"` for Hatch-managed, `"❌"` for third-party +- Shows ALL servers on hosts (both Hatch-managed and third-party) +- Environment column: environment name if Hatch-managed, `"-"` otherwise +- Sorted by: host (alphabetically), then server -```text -Configured hosts for environment 'my-project': - claude-desktop (2 packages): - - weather-toolkit: ~/.claude/config.json (configured: 2025-09-25T10:00:00) - - news-aggregator: ~/.claude/config.json (configured: 2025-09-25T11:30:00) - cursor (1 package): - - weather-toolkit: ~/.cursor/config.json (configured: 2025-09-25T10:15:00) +#### `hatch mcp list servers` + +List server/host pairs from host configuration files. + +**Purpose**: Shows ALL servers on hosts (both Hatch-managed and third-party) with Hatch management status. + +Syntax: + +`hatch mcp list servers [--host PATTERN] [--json]` + +| Flag | Type | Description | Default | +|---:|---|---|---| +| `--host` | string | Filter by host name using regex pattern | none | +| `--json` | flag | Output in JSON format | false | + +**Example Output**: + +```bash +$ hatch mcp list servers +MCP Servers: + Server Host Hatch Environment + ───────────────────────────────────────────────────────────────── + third-party-tool claude-desktop ❌ - + weather-server claude-desktop βœ… default + weather-server cursor βœ… default ``` +**Key Details**: +- Header: `"MCP Servers:"` +- Columns: Server (width 18), Host (width 18), Hatch (width 8), Environment (width 15) +- Hatch column: `"βœ…"` for Hatch-managed, `"❌"` for third-party +- Shows ALL servers on hosts (both Hatch-managed and third-party) +- Environment column: environment name if Hatch-managed, `"-"` otherwise +- Sorted by: server (alphabetically), then host + +#### `hatch mcp show hosts` + +Show detailed hierarchical view of all MCP host configurations. + +**Purpose**: Displays comprehensive configuration details for all hosts with their servers. + +Syntax: + +`hatch mcp show hosts [--server PATTERN] [--json]` + +| Flag | Type | Description | Default | +|---:|---|---|---| +| `--server` | string | Filter by server name using regex pattern | none | +| `--json` | flag | Output in JSON format | false | + **Example Output**: -```text -Available MCP Host Platforms: -βœ“ claude-desktop Available /Users/user/.claude/config.json -βœ“ cursor Available /Users/user/.cursor/config.json -βœ— vscode Not Found /Users/user/.vscode/settings.json -βœ— lmstudio Not Found /Users/user/.lmstudio/config.json +```bash +$ hatch mcp show hosts +═══════════════════════════════════════════════════════════════════════════════ +MCP Host: claude-desktop + Config Path: /Users/user/.config/claude/claude_desktop_config.json + Last Modified: 2026-02-01 15:30:00 + Backup Available: Yes (3 backups) + + Configured Servers (2): + weather-server (Hatch-managed: default) + Command: python + Args: ['-m', 'weather_server'] + Environment Variables: + API_KEY: ****** (hidden) + DEBUG: true + Last Synced: 2026-02-01 15:30:00 + Package Version: 1.0.0 + + third-party-tool (Not Hatch-managed) + Command: node + Args: ['server.js'] + +═══════════════════════════════════════════════════════════════════════════════ +MCP Host: cursor + Config Path: /Users/user/.cursor/mcp.json + Last Modified: 2026-02-01 14:20:00 + Backup Available: No + + Configured Servers (1): + weather-server (Hatch-managed: default) + Command: python + Args: ['-m', 'weather_server'] + Last Synced: 2026-02-01 14:20:00 + Package Version: 1.0.0 ``` -#### `hatch mcp list servers` +**Key Details**: +- Separator: `"═" * 79` (U+2550) between hosts +- Host and server names highlighted (bold + amber when colors enabled) +- Hatch-managed servers show: `"(Hatch-managed: {environment})"` +- Third-party servers show: `"(Not Hatch-managed)"` +- Sensitive environment variables shown as `"****** (hidden)"` +- Hierarchical structure with 2-space indentation per level -List MCP servers from environment with host configuration tracking information. +#### `hatch mcp show servers` -**Purpose**: Shows servers from environment packages with detailed host configuration tracking, including which hosts each server is configured on and last sync timestamps. +Show detailed hierarchical view of all MCP server configurations across hosts. + +**Purpose**: Displays comprehensive configuration details for all servers across their host deployments. Syntax: -`hatch mcp list servers [--env ENV]` +`hatch mcp show servers [--host PATTERN] [--json]` | Flag | Type | Description | Default | |---:|---|---|---| -| `--env`, `-e` | string | Environment name (defaults to current) | current environment | +| `--host` | string | Filter by host name using regex pattern | none | +| `--json` | flag | Output in JSON format | false | **Example Output**: -```text -MCP servers in environment 'default': -Server Name Package Version Command --------------------------------------------------------------------------------- -weather-server weather-toolkit 1.0.0 python weather.py - Configured on hosts: - claude-desktop: /Users/user/.claude/config.json (last synced: 2025-09-24T10:00:00) - cursor: /Users/user/.cursor/config.json (last synced: 2025-09-24T09:30:00) - -news-aggregator news-toolkit 2.1.0 python news.py - Configured on hosts: - claude-desktop: /Users/user/.claude/config.json (last synced: 2025-09-24T10:00:00) +```bash +$ hatch mcp show servers +═══════════════════════════════════════════════════════════════════════════════ +MCP Server: weather-server + Hatch Managed: Yes (default) + Package Version: 1.0.0 + + Host Configurations (2): + claude-desktop: + Command: python + Args: ['-m', 'weather_server'] + Environment Variables: + API_KEY: ****** (hidden) + DEBUG: true + Last Synced: 2026-02-01 15:30:00 + + cursor: + Command: python + Args: ['-m', 'weather_server'] + Last Synced: 2026-02-01 14:20:00 + +═══════════════════════════════════════════════════════════════════════════════ +MCP Server: third-party-tool + Hatch Managed: No + + Host Configurations (1): + claude-desktop: + Command: node + Args: ['server.js'] ``` +**Key Details**: +- Separator: `"═" * 79` between servers +- Server and host names highlighted (bold + amber when colors enabled) +- Hatch-managed servers show: `"Hatch Managed: Yes ({environment})"` +- Third-party servers show: `"Hatch Managed: No"` +- Hierarchical structure with 2-space indentation per level + #### `hatch mcp discover hosts` Discover available MCP host platforms on the system. @@ -729,6 +1000,32 @@ Discover available MCP host platforms on the system. Syntax: +`hatch mcp discover hosts [--json]` + +| Flag | Type | Description | Default | +|---:|---|---|---| +| `--json` | flag | Output in JSON format | false | + +**Example Output**: + +```bash +$ hatch mcp discover hosts +Available MCP Host Platforms: + Host Status Config Path + ───────────────────────────────────────────────────────────────── + claude-desktop βœ“ Available /Users/user/.config/claude/... + cursor βœ“ Available /Users/user/.cursor/mcp.json + vscode βœ— Not Found - +``` + +**Key Details**: +- Header: `"Available MCP Host Platforms:"` +- Columns: Host (width 18), Status (width 15), Config Path (width "auto") +- Status: `"βœ“ Available"` or `"βœ— Not Found"` +- Shows ALL host types (MCPHostType enum), not just available ones + +Syntax: + `hatch mcp discover hosts` **Example Output**: @@ -812,5 +1109,5 @@ Syntax: ## Notes -- The implementation in `hatch/cli_hatch.py` does not provide a `--version` flag or a top-level `version` command. Use `hatch --help` to inspect available commands and options. -- This reference mirrors the command names and option names implemented in `hatch/cli_hatch.py`. If you change CLI arguments in code, update this file to keep documentation in sync. +- The CLI is implemented in the `hatch/cli/` package with modular handler modules. Use `hatch --help` to inspect available commands and options. +- This reference mirrors the command names and option names implemented in the CLI handlers. If you change CLI arguments in code, update this file to keep documentation in sync. diff --git a/docs/articles/users/GettingStarted.md b/docs/articles/users/GettingStarted.md index 0d3ec31..034337d 100644 --- a/docs/articles/users/GettingStarted.md +++ b/docs/articles/users/GettingStarted.md @@ -152,6 +152,40 @@ hatch package list For more in-depth information, please refer to the [tutorials](tutorials/01-getting-started/01-installation.md) section. +## Quick Reference: Viewing Commands + +Hatch provides multiple commands for viewing your environments, packages, and host configurations: + +### Environment Views + +- `hatch env list`: List all environments with package counts +- `hatch env show `: Detailed view of specific environment +- `hatch env list hosts`: View environment deployments by host +- `hatch env list servers`: View environment deployments by server + +### MCP Host Views + +- `hatch mcp list hosts`: Table view of hosts and servers +- `hatch mcp list servers`: Table view of servers and hosts +- `hatch mcp show hosts`: Detailed view of all host configurations +- `hatch mcp show servers`: Detailed view of all server configurations + +### Discovery + +- `hatch mcp discover hosts`: Detect available MCP host platforms + +**Filtering**: All list and show commands support regex filtering: +```bash +# Filter by server name +hatch mcp list hosts --server "weather.*" + +# Filter by host name +hatch mcp show servers --host "claude.*" + +# Filter by environment +hatch env list hosts --env "my-project" +``` + ## Understanding Hatch Concepts ### Environments diff --git a/docs/articles/users/MCPHostConfiguration.md b/docs/articles/users/MCPHostConfiguration.md index 86ed277..9e2d2bf 100644 --- a/docs/articles/users/MCPHostConfiguration.md +++ b/docs/articles/users/MCPHostConfiguration.md @@ -68,6 +68,45 @@ hatch mcp list servers hatch mcp list servers --env-var production ``` +### Viewing Host Configurations + +Hatch provides multiple ways to view MCP host configurations: + +**Table Views** (for quick overview): +- `hatch mcp list hosts`: View all hosts and their servers +- `hatch mcp list servers`: View all servers and their hosts + +**Detailed Views** (for comprehensive information): +- `hatch mcp show hosts`: Detailed view of all host configurations +- `hatch mcp show servers`: Detailed view of all server configurations + +**Filtering**: +All commands support regex filtering: +- `hatch mcp list hosts --server "weather.*"`: Show only servers matching pattern +- `hatch mcp show servers --host "claude.*"`: Show only hosts matching pattern + +**Examples**: + +```bash +# View all hosts with their servers (table view) +hatch mcp list hosts + +# View all servers with their hosts (table view) +hatch mcp list servers + +# View detailed host configurations +hatch mcp show hosts + +# View detailed server configurations +hatch mcp show servers + +# Filter by server name using regex +hatch mcp show hosts --server "weather.*" + +# Filter by host name using regex +hatch mcp show servers --host "claude.*" +``` + ### Remove a Server Remove an MCP server from a host: @@ -214,6 +253,20 @@ The system validates host names against available MCP host types: - `gemini` - Additional hosts as configured -Invalid host names result in clear error messages with available options listed. +All error messages use standardized formatting with structured details: + +``` +[ERROR] Failed to configure MCP server 'my-server' + Host: claude-desktop + Reason: Server configuration invalid for claude-desktop +``` + +Invalid host names result in clear error messages with available options listed: + +``` +[ERROR] Invalid host 'vsc' + Field: --host + Suggestion: Supported hosts: claude-desktop, vscode, cursor, kiro, lmstudio, gemini +``` For complete command syntax and all available options, see [CLI Reference](CLIReference.md). diff --git a/docs/articles/users/SecurityAndTrust.md b/docs/articles/users/SecurityAndTrust.md index dd50868..2ddde79 100644 --- a/docs/articles/users/SecurityAndTrust.md +++ b/docs/articles/users/SecurityAndTrust.md @@ -42,7 +42,7 @@ Different installer types have varying privilege implications: #### Docker Installer (`docker_installer.py`) -- Manages Docker image dependencies +- Manages Docker image dependencies - Requires Docker daemon access - Images run with Docker's security model @@ -122,7 +122,7 @@ Always review dependency specifications in `hatch_metadata.json`: ], "system": [ { - "name": "curl", + "name": "curl", "version_constraint": ">=7.0.0", "package_manager": "apt" } diff --git a/docs/articles/users/Troubleshooting/ReportIssues.md b/docs/articles/users/Troubleshooting/ReportIssues.md index 76edbe5..2c5bec4 100644 --- a/docs/articles/users/Troubleshooting/ReportIssues.md +++ b/docs/articles/users/Troubleshooting/ReportIssues.md @@ -94,7 +94,7 @@ Paste the following to [report an issue](https://github.com/CrackingShells/Hatch ### Environment: - OS: Windows 10/11 / macOS / Linux (include distro and version) -- Hatch version: +- Hatch version: ### Command: diff --git a/docs/articles/users/tutorials/01-getting-started/01-installation.md b/docs/articles/users/tutorials/01-getting-started/01-installation.md index 3ba2232..b4a3159 100644 --- a/docs/articles/users/tutorials/01-getting-started/01-installation.md +++ b/docs/articles/users/tutorials/01-getting-started/01-installation.md @@ -65,7 +65,7 @@ View detailed help for specific command groups: # Environment management hatch env --help -# Package management +# Package management hatch package --help ``` @@ -78,7 +78,7 @@ Explore the help output for the `create` command. What options are available for ```bash # positional arguments: # name Package name -# +# # options: # -h, --help show this help message and exit # --dir DIR, -d DIR Target directory (default: current directory) diff --git a/docs/articles/users/tutorials/01-getting-started/02-create-env.md b/docs/articles/users/tutorials/01-getting-started/02-create-env.md index fc9243d..a151376 100644 --- a/docs/articles/users/tutorials/01-getting-started/02-create-env.md +++ b/docs/articles/users/tutorials/01-getting-started/02-create-env.md @@ -62,18 +62,18 @@ hatch env list You should see output similar to: ```txt -Available environments: - my_first_env - My first Hatch environment - Python: Not configured - my_python_env - Environment with Python support - Python: 3.11.x (conda: my_python_env) - -Python Environment Manager: - Conda executable: /path/to/conda - Mamba executable: /path/to/mamba - Preferred manager: mamba +Environments: + Name Python Packages + ─────────────────────────────────────── + * my_first_env - 0 + my_python_env 3.11.5 0 ``` +**Key Details**: +- Current environment marked with `*` prefix +- Python column shows version or `-` if no Python environment +- Packages column shows count of installed packages + **Exercise:** Initialize a Python environment inside `my_first_env`. Try both initializing without `hatch_mcp_server` wrapper and adding it afterwards. Hint: Use `hatch env python --help` to explore available Python subcommands and flags. @@ -98,5 +98,5 @@ hatch env python info --hatch_env my_first_env # hatch_mcp_server should now app In most use cases, you'll want to create environments with Python integration and the hatch_mcp_server wrapper. However, Hatch provides flexibility to customize your environments as needed. -> Previous: [Installation](01-installation.md) +> Previous: [Installation](01-installation.md) > Next: [Install Package](03-install-package.md) diff --git a/docs/articles/users/tutorials/01-getting-started/03-install-package.md b/docs/articles/users/tutorials/01-getting-started/03-install-package.md index 1944163..94d542c 100644 --- a/docs/articles/users/tutorials/01-getting-started/03-install-package.md +++ b/docs/articles/users/tutorials/01-getting-started/03-install-package.md @@ -53,7 +53,7 @@ No additional dependencies to install. Total packages to install: 1 ============================================================ -Proceed with installation? [y/N]: +Proceed with installation? [y/N]: ``` For automated scenarios, use `--auto-approve` to skip confirmation prompts: @@ -82,17 +82,44 @@ If you don't have a local package yet, you can create one using the `hatch creat ## Step 4: Verify Installation -List installed packages in your environment: +Check that the package was installed: ```bash -hatch package list --env my_python_env +hatch env list ``` -Output shows package details: +You should see the package count updated: ```txt -Packages in environment 'my_python_env': -my-package (1.0.0) Hatch compliant: true source: file:///path/to/package location: /env/path/my-package +Environments: + Name Python Packages + ─────────────────────────────────────── + * my_python_env 3.11.5 1 +``` + +For detailed package information, use `hatch env show`: + +```bash +hatch env show my_python_env +``` + +Output shows complete package details: + +```txt +Environment: my_python_env (active) + Description: Environment with Python support + Created: 2026-02-01 10:00:00 + + Python Environment: + Version: 3.11.5 + Executable: /path/to/python + Status: Active + + Packages (1): + base_pkg_1 + Version: 1.0.3 + Source: registry (https://registry.example.com) + Deployed to: (none) ``` ## Step 5: Understanding Package Dependencies @@ -136,5 +163,5 @@ YYYY-MM-DD HH:MM:SS - hatch.package_loader - INFO - Using cached package base_pk -> Previous: [Create Environment](02-create-env.md) +> Previous: [Create Environment](02-create-env.md) > Next: [Checkpoint](04-checkpoint.md) diff --git a/docs/articles/users/tutorials/02-environments/01-manage-envs.md b/docs/articles/users/tutorials/02-environments/01-manage-envs.md index d2d2390..00c6400 100644 --- a/docs/articles/users/tutorials/02-environments/01-manage-envs.md +++ b/docs/articles/users/tutorials/02-environments/01-manage-envs.md @@ -36,19 +36,17 @@ hatch env list Example output: ```txt -Available environments: -* my_python_env - Environment with Python support - Python: 3.11.9 (conda: my_python_env) - my_first_env - My first Hatch environment - Python: 3.13.5 (conda: my_first_env) - -Python Environment Manager: - Conda executable: /usr/local/bin/conda - Mamba executable: /usr/local/bin/mamba - Preferred manager: mamba +Environments: + Name Python Packages + ─────────────────────────────────────── + * my_python_env 3.11.9 0 + my_first_env 3.13.5 0 ``` -The `*` indicates the current active environment. +**Key Details**: +- The `*` indicates the current active environment +- Python column shows version number (or `-` if no Python environment) +- Packages column shows count of installed packages ## Step 2: Switch Between Environments @@ -58,6 +56,12 @@ Change your current working environment: hatch env use my_first_env ``` +Expected output: + +```txt +[SET] Current environment β†’ 'my_first_env' +``` + Verify the switch: ```bash @@ -78,22 +82,37 @@ Remove an environment you no longer need: hatch env remove my_first_env ``` +Expected output: + +```txt +[REMOVE] Environment 'my_first_env' + +Proceed? [y/N]: y +[REMOVED] Environment 'my_first_env' +``` + **Important:** This removes both the Hatch environment and any associated Python environment. Make sure to back up any important data first. +**Note**: The command will prompt for confirmation unless you use `--auto-approve`. + ## Step 4: Understanding Environment Information -The `env list` command provides detailed information: +The `env list` command displays environments in a table format with: -- **Environment name and description** - Basic identification -- **Current environment marker (*)** - Shows which environment is active -- **Python environment status** - Shows Python version and conda environment name -- **Python Environment Manager status** - Shows available conda/mamba executables +- **Name column** - Environment name with `*` marker for current environment +- **Python column** - Python version (or `-` if no Python environment) +- **Packages column** - Count of installed packages -If conda/mamba is not available, you'll see: +For detailed information about a specific environment, including descriptions and full package details, use: +```bash +hatch env show ``` -Python Environment Manager: Conda/mamba not available -``` + +This will display: +- Environment description and creation date +- Python environment details (version, executable path, conda environment name) +- Complete list of installed packages with versions and deployment status ## Step 5: Managing Multiple Environments @@ -108,7 +127,7 @@ hatch env create project_b --description "Environment for Project B" --python-ve hatch env use project_a # Work on project A... -hatch env use project_b +hatch env use project_b # Work on project B... ``` @@ -121,7 +140,7 @@ Create three environments with different Python versions, switch between them, a ```bash # Create environments hatch env create env_311 --python-version 3.11 --description "Python 3.11 environment" -hatch env create env_312 --python-version 3.12 --description "Python 3.12 environment" +hatch env create env_312 --python-version 3.12 --description "Python 3.12 environment" hatch env create env_313 --python-version 3.13 --description "Python 3.13 environment" # Switch between them @@ -140,5 +159,5 @@ hatch env remove env_313 -> Previous: [Getting Started Checkpoint](../01-getting-started/04-checkpoint.md) +> Previous: [Getting Started Checkpoint](../01-getting-started/04-checkpoint.md) > Next: [Python Environment Management](02-python-env.md) diff --git a/docs/articles/users/tutorials/02-environments/02-python-env.md b/docs/articles/users/tutorials/02-environments/02-python-env.md index a260baa..e59a24f 100644 --- a/docs/articles/users/tutorials/02-environments/02-python-env.md +++ b/docs/articles/users/tutorials/02-environments/02-python-env.md @@ -4,7 +4,7 @@ **Concepts covered:** - Advanced Python environment operations -- Python environment initialization and configuration +- Python environment initialization and configuration - Environment diagnostics and troubleshooting - Hatch MCP server wrapper management @@ -104,7 +104,7 @@ Remove only the Python environment while keeping the Hatch environment: # With confirmation prompt hatch env python remove --hatch_env my_env -# Force removal without prompt +# Force removal without prompt hatch env python remove --hatch_env my_env --force ``` @@ -162,5 +162,5 @@ hatch env list -> Previous: [Manage Environments](01-manage-envs.md) +> Previous: [Manage Environments](01-manage-envs.md) > Next: [Checkpoint](03-checkpoint.md) diff --git a/docs/articles/users/tutorials/03-author-package/01-generate-template.md b/docs/articles/users/tutorials/03-author-package/01-generate-template.md index 0d15e94..aaa2cc0 100644 --- a/docs/articles/users/tutorials/03-author-package/01-generate-template.md +++ b/docs/articles/users/tutorials/03-author-package/01-generate-template.md @@ -73,10 +73,10 @@ mcp = FastMCP("my_new_package", log_level="WARNING") @mcp.tool() def example_tool(param: str) -> str: """Example tool function. - + Args: param (str): Example parameter. - + Returns: str: Example result.""" @@ -147,7 +147,7 @@ hatch create described-package --description "A package that demonstrates detail # Examine the differences cat basic-package/hatch_metadata.json -cat my-packages/custom_package/hatch_metadata.json +cat my-packages/custom_package/hatch_metadata.json cat described-package/hatch_metadata.json ``` diff --git a/docs/articles/users/tutorials/03-author-package/02-implement-functionality.md b/docs/articles/users/tutorials/03-author-package/02-implement-functionality.md index 5cbdc32..6b23700 100644 --- a/docs/articles/users/tutorials/03-author-package/02-implement-functionality.md +++ b/docs/articles/users/tutorials/03-author-package/02-implement-functionality.md @@ -43,11 +43,11 @@ mcp = FastMCP("ArithmeticTools", log_level="WARNING") @mcp.tool() def add(a: float, b: float) -> float: """Add two numbers together. - + Args: a (float): First number. b (float): Second number. - + Returns: float: Sum of a and b. """ @@ -56,11 +56,11 @@ def add(a: float, b: float) -> float: @mcp.tool() def subtract(a: float, b: float) -> float: """Subtract second number from first number. - + Args: a (float): First number. b (float): Second number. - + Returns: float: Difference (a - b). """ @@ -69,11 +69,11 @@ def subtract(a: float, b: float) -> float: @mcp.tool() def multiply(a: float, b: float) -> float: """Multiply two numbers together. - + Args: a (float): First number. b (float): Second number. - + Returns: float: Product of a and b. """ @@ -82,27 +82,27 @@ def multiply(a: float, b: float) -> float: @mcp.tool() def divide(a: float, b: float) -> float: """Divide first number by second number. - + Args: a (float): First number (dividend). b (float): Second number (divisor). - + Returns: float: Quotient (a / b). """ if b == 0: raise ValueError("Cannot divide by zero") - + return a / b @mcp.tool() def power(base: float, exponent: float) -> float: """Raise a number to the power of another number. - + Args: base (float): The base number. exponent (float): The exponent (power). - + Returns: float: Result of raising base to the power of exponent. """ diff --git a/docs/articles/users/tutorials/03-author-package/03-edit-metadata.md b/docs/articles/users/tutorials/03-author-package/03-edit-metadata.md index 73188d5..a3c5517 100644 --- a/docs/articles/users/tutorials/03-author-package/03-edit-metadata.md +++ b/docs/articles/users/tutorials/03-author-package/03-edit-metadata.md @@ -33,7 +33,7 @@ Every package must include these fields: { "package_schema_version": "1.2.1", "name": "package_name", - "version": "0.1.0", + "version": "0.1.0", "entry_point": "hatch_mcp_server_entry.py", "description": "Package description", "tags": [], @@ -63,7 +63,7 @@ Edit the basic package information: }, "contributors": [ { - "name": "Contributor Name", + "name": "Contributor Name", "email": "contributor@example.com" } ], @@ -151,7 +151,7 @@ Configure dependencies based on your implementation. For our arithmetic server t - `==1.0.0` - Exact version - `>=1.0.0` - Minimum version -- `<=2.0.0` - Maximum version +- `<=2.0.0` - Maximum version - `!=1.5.0` - Exclude specific version ## Step 4: Set Compatibility Requirements diff --git a/docs/articles/users/tutorials/03-author-package/04-validate-and-install.md b/docs/articles/users/tutorials/03-author-package/04-validate-and-install.md index 5dcffa4..92d294d 100644 --- a/docs/articles/users/tutorials/03-author-package/04-validate-and-install.md +++ b/docs/articles/users/tutorials/03-author-package/04-validate-and-install.md @@ -39,7 +39,8 @@ The validation process checks: ### Successful Validation ```txt -Package validation SUCCESSFUL: /path/to/my_package +[SUCCESS] Operation completed: + [VALIDATED] Package 'my_package' ``` The command will exit with status code 0 when validation succeeds. @@ -74,7 +75,7 @@ The command will exit with status code 1 when validation fails. ### Invalid Package Name ```json -// ❌ Invalid - contains hyphens +// ❌ Invalid - contains hyphens "name": "my_package" // βœ… Valid - uses underscores @@ -176,7 +177,7 @@ hatch create test-package # Invalid name with hyphens hatch validate test-package # 3. Fix errors: -# - Change name to "test_package" +# - Change name to "test_package" # - Add missing required fields # - Use proper version format like "1.0.0" diff --git a/docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md b/docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md index 64f271d..05a14f9 100644 --- a/docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md +++ b/docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md @@ -115,22 +115,20 @@ Hatch currently supports configuration for these MCP host platforms: hatch mcp discover hosts ``` -**Possible Output (depending on the software you have installed)**: +**Example Output (depending on the software you have installed)**: ```plaintext -Available MCP host platforms: - claude-desktop: βœ“ Available - Config path: path/to/claude_desktop_config.json - claude-code: βœ— Not detected - Config path: path/to/.claude/mcp_config.json - vscode: βœ— Not detected - Config path: path/to/.vscode/settings.json - cursor: βœ“ Available - Config path: path/to/.cursor/mcp.json - lmstudio: βœ“ Available - Config path: path/toLMStudio/mcp.json - gemini: βœ“ Available - Config path: path/to/.gemini/settings.json +Available MCP Host Platforms: + Host Status Config Path + ───────────────────────────────────────────────────────────────── + claude-desktop βœ“ Available /Users/user/.config/claude/claude_desktop_config.json + claude-code βœ— Not Found - + vscode βœ— Not Found - + cursor βœ“ Available /Users/user/.cursor/mcp.json + kiro βœ— Not Found - + codex βœ— Not Found - + lmstudio βœ“ Available /Users/user/Library/Application Support/LMStudio/mcp.json + gemini βœ“ Available /Users/user/.gemini/settings.json ``` ### Check Current Environment diff --git a/docs/articles/users/tutorials/04-mcp-host-configuration/02-configuring-hatch-packages.md b/docs/articles/users/tutorials/04-mcp-host-configuration/02-configuring-hatch-packages.md index a6cb022..a3642ae 100644 --- a/docs/articles/users/tutorials/04-mcp-host-configuration/02-configuring-hatch-packages.md +++ b/docs/articles/users/tutorials/04-mcp-host-configuration/02-configuring-hatch-packages.md @@ -4,7 +4,7 @@ **Concepts covered:** - Hatch package deployment with automatic dependency resolution -- `hatch package add --host` and `hatch package sync` commands +- `hatch package add --host` and `hatch package sync` commands - Guaranteed dependency installation (Python, apt, Docker, other Hatch packages) - Package-first deployment advantages over direct configuration @@ -29,7 +29,7 @@ Hatch packages include complete dependency specifications that are automatically # Package deployment handles ALL dependencies automatically hatch package add my-weather-server --host claude-desktop # βœ… Installs Python dependencies (requests, numpy, etc.) -# βœ… Installs system dependencies (curl, git, etc.) +# βœ… Installs system dependencies (curl, git, etc.) # βœ… Installs Docker containers if specified # βœ… Installs other Hatch package dependencies # βœ… Configures MCP server on Claude Desktop @@ -46,7 +46,7 @@ hatch package add my-weather-server --host claude-desktop **Direct Configuration (Advanced)**: - ❌ Manual dependency management required -- ❌ No compatibility guarantees +- ❌ No compatibility guarantees - ❌ Multiple setup steps - ❌ Potential environment conflicts - ❌ Limited rollback options @@ -69,10 +69,11 @@ hatch package add . --host claude-desktop **Expected Output**: ``` -Successfully added package: my_new_package +[SUCCESS] Operation completed: + [ADDED] Package 'my_new_package' + Configuring MCP server for package 'my_new_package' on 1 host(s)... -βœ“ Configured my_new_package (my_new_package) on claude-desktop -MCP configuration completed: 1/1 hosts configured +βœ“ Configured my_new_package on claude-desktop ``` ### Verify Deployment @@ -123,18 +124,9 @@ hatch package list ```bash # Sync a specific package to hosts hatch package sync my-weather-server --host claude-desktop - -# Sync multiple packages -hatch package sync weather-server,news-api --host all ``` -### Sync All Packages - -```bash -# Sync all packages in current environment to hosts -hatch package sync --host claude-desktop,cursor -``` -The `hatch package sync` command syncs all packages that are already installed in the current environment. +**Note**: The `hatch package sync` command requires a package name. To sync all packages from an environment to hosts, use `hatch mcp sync --from-env --to-host ` (covered in [Tutorial 04-04](04-environment-synchronization.md)). ## Step 4: Validate Dependency Resolution @@ -186,7 +178,7 @@ hatch package add . --host claude-desktop ### Production Environment ```bash -# Switch to production environment +# Switch to production environment hatch env use production # Deploy with production settings diff --git a/docs/articles/users/tutorials/04-mcp-host-configuration/04-environment-synchronization.md b/docs/articles/users/tutorials/04-mcp-host-configuration/04-environment-synchronization.md index 4a545ad..d049194 100644 --- a/docs/articles/users/tutorials/04-mcp-host-configuration/04-environment-synchronization.md +++ b/docs/articles/users/tutorials/04-mcp-host-configuration/04-environment-synchronization.md @@ -121,11 +121,14 @@ hatch mcp sync --from-env project_alpha --to-host claude-desktop,cursor **Expected Output**: ```text -Synchronize MCP configurations from host 'claude-desktop' to 1 host(s)? [y/N]: y -[SUCCESS] Synchronization completed - Servers synced: 4 - Hosts updated: 1 - βœ“ cursor (backup: path\to\.hatch\mcp_host_config_backups\cursor\mcp.json.cursor.20251124_225305_495653) +[SYNC] MCP configurations from environment 'project_alpha' to 2 host(s) + +Proceed? [y/N]: y +[SUCCESS] Operation completed: + [SYNCED] Servers synced: 4 + [UPDATED] Hosts updated: 2 + [CREATED] Backup: ~/.hatch/mcp_host_config_backups/cursor/mcp.json.cursor.20251124_225305_495653 + [CREATED] Backup: ~/.hatch/mcp_host_config_backups/claude-desktop/mcp.json.claude-desktop.20251124_225306_123456 ``` ### Deploy Project-Beta to All Hosts @@ -145,12 +148,16 @@ hatch mcp sync --from-env project_beta --to-host all Check what was deployed to each host for each project: ```bash -# Check project_alpha deployments -hatch env use project_alpha -hatch mcp list servers +# View environment deployments by host (environment β†’ host β†’ server) +hatch env list hosts --env project_alpha -# Check project_beta deployments -hatch env use project_beta +# View environment deployments by server (environment β†’ server β†’ host) +hatch env list servers --env project_alpha + +# Check host configurations (shows all servers on all hosts) +hatch mcp list hosts + +# Check server configurations (shows all servers across hosts) hatch mcp list servers ``` @@ -223,12 +230,23 @@ Will restore the latest backup available. For a more granular restoration, you c Use environment-scoped commands to verify your project configurations: ```bash -# Check project_alpha server deployments -hatch env use project_alpha -hatch mcp list servers +# View environment deployments by host +hatch env list hosts --env project_alpha -# Check which hosts have project_alpha servers configured -hatch mcp list hosts +# View environment deployments by server +hatch env list servers --env project_alpha + +# View detailed host configurations +hatch mcp show hosts + +# View detailed server configurations +hatch mcp show servers + +# Filter by server name using regex +hatch mcp show hosts --server "weather.*" + +# Filter by host name using regex +hatch mcp show servers --host "claude.*" ``` ### Common Project Isolation Issues @@ -258,7 +276,7 @@ Hatch creates automatic backups before any configuration changes. You don't need ```bash # List available backups (always created automatically) -hatch mcp backup list --host claude-desktop +hatch mcp backup list claude-desktop # Clean old backups if needed hatch mcp backup clean claude-desktop --keep-count 10 @@ -267,8 +285,11 @@ hatch mcp backup clean claude-desktop --keep-count 10 **Restore Project Configuration**: ```bash -# Restore from specific backup -hatch mcp backup restore claude-desktop project_alpha-stable +# Restore latest backup +hatch mcp backup restore claude-desktop + +# Restore from specific backup file +hatch mcp backup restore claude-desktop --backup-file mcp.json.claude-desktop.20231201_143022 # Then re-sync current project if needed hatch env use project_alpha diff --git a/docs/articles/users/tutorials/04-mcp-host-configuration/05-checkpoint.md b/docs/articles/users/tutorials/04-mcp-host-configuration/05-checkpoint.md index 0799ac0..0542800 100644 --- a/docs/articles/users/tutorials/04-mcp-host-configuration/05-checkpoint.md +++ b/docs/articles/users/tutorials/04-mcp-host-configuration/05-checkpoint.md @@ -12,15 +12,15 @@ You now have comprehensive skills for managing MCP server deployments across dif ## Skills Mastery Summary ### Package-First Deployment -βœ… **Automatic Dependency Resolution**: Deploy Hatch packages with guaranteed dependency installation -βœ… **Multi-Host Deployment**: Deploy packages to multiple host platforms simultaneously -βœ… **Environment Integration**: Use Hatch environment isolation for organized deployments +βœ… **Automatic Dependency Resolution**: Deploy Hatch packages with guaranteed dependency installation +βœ… **Multi-Host Deployment**: Deploy packages to multiple host platforms simultaneously +βœ… **Environment Integration**: Use Hatch environment isolation for organized deployments βœ… **Rollback Capabilities**: Use automatic backups for safe deployments ### Direct Server Configuration (Advanced Method) βœ… **Third-Party Integration**: Configure arbitrary MCP servers not packaged with Hatch βœ… **Cross-Environment Deployment**: Synchronize MCP configurations between Hatch environments and hosts -βœ… **Host-to-Host Copying**: Replicate configurations directly between host platforms +βœ… **Host-to-Host Copying**: Replicate configurations directly between host platforms βœ… **Pattern-Based Filtering**: Use regular expressions for precise server selection ## Deployment Strategy Decision Framework @@ -120,12 +120,16 @@ You now have comprehensive skills for managing MCP server deployments across dif **Environment Issues**: - List available environments with `hatch env list` - Verify current environment with `hatch env current` -- Check package installation with `hatch package list` +- View environment details with `hatch env show ` **Practical Diagnostics**: - Check host platform detection: `hatch mcp discover hosts` -- List configured servers: `hatch mcp list servers --env ` -- Check server configuration details: `hatch mcp list servers --env --host ` +- List environment deployments by host: `hatch env list hosts --env ` +- List environment deployments by server: `hatch env list servers --env ` +- List host/server pairs from host configs: `hatch mcp list hosts` +- List server/host pairs from host configs: `hatch mcp list servers` +- View detailed host configurations: `hatch mcp show hosts` +- View detailed server configurations: `hatch mcp show servers` - Validate package structure: `hatch validate ` - Test configuration preview: `--dry-run` flag on any command - Check backup status: `hatch mcp backup list ` diff --git a/docs/resources/diagrams/architecture.puml b/docs/resources/diagrams/architecture.puml index 9dd8ebd..d1abfef 100644 --- a/docs/resources/diagrams/architecture.puml +++ b/docs/resources/diagrams/architecture.puml @@ -6,7 +6,9 @@ LAYOUT_WITH_LEGEND() title Hatch Architecture Overview Container_Boundary(cli, "CLI Layer") { - Component(cli_hatch, "CLI Interface", "Python", "Command-line interface\nArgument parsing and validation") + Component(cli_main, "CLI Entry Point", "Python", "Argument parsing\nCommand routing") + Component(cli_handlers, "CLI Handlers", "Python", "Domain-specific handlers\n(mcp, env, package, system)") + Component(cli_utils, "CLI Utilities", "Python", "Shared utilities\nExit codes, parsing helpers") } Container_Boundary(core, "Core Management") { @@ -28,7 +30,7 @@ Container_Boundary(installation, "Installation System") { Component(orchestrator, "Dependency Orchestrator", "Python", "Multi-type dependency coordination\nInstallation planning\nProgress reporting") Component(installation_context, "Installation Context", "Python", "Installation state management\nEnvironment isolation\nProgress tracking") Component(installer_base, "Installer Base", "Python", "Common installer interface\nError handling patterns\nResult aggregation") - + Component(python_installer, "Python Installer", "Python", "Pip package installation\nConda environment integration") Component(system_installer, "System Installer", "Python", "System package installation\nPrivilege management\nAPT/package manager integration") Component(docker_installer, "Docker Installer", "Python", "Docker image management\nRegistry authentication\nImage version handling") @@ -48,9 +50,11 @@ Container_Boundary(external, "External Systems") { } ' CLI relationships -Rel(cli_hatch, env_manager, "Manages environments") -Rel(cli_hatch, package_loader, "Loads and validates packages") -Rel(cli_hatch, template_generator, "Creates package templates") +Rel(cli_main, cli_handlers, "Routes to") +Rel(cli_handlers, cli_utils, "Uses") +Rel(cli_handlers, env_manager, "Manages environments") +Rel(cli_handlers, package_loader, "Loads and validates packages") +Rel(cli_handlers, template_generator, "Creates package templates") ' Core management relationships Rel(env_manager, python_env_manager, "Delegates Python operations") diff --git a/docs/resources/images/architecture.svg b/docs/resources/images/architecture.svg index c31f7cd..7fec9b4 100644 --- a/docs/resources/images/architecture.svg +++ b/docs/resources/images/architecture.svg @@ -1 +1 @@ -Hatch Architecture OverviewHatch Architecture OverviewCLI Layer[container]Core Management[container]Package System[container]Registry System[container]Installation System[container]Validation System[container]External Systems[container]CLI Interface[Python] Command-line interfaceArgument parsing andvalidationEnvironment Manager[Python] Environment lifecycleMetadata persistenceCurrent environmenttrackingPython EnvironmentManager[Python] Conda/mamba integrationPython executableresolutionPackage installationcoordinationPackage Loader[Python] Local package inspectionMetadata validationStructure verificationTemplate Generator[Python] Package template creationBoilerplate file generationDefault metadata setupRegistry Retriever[Python] Package downloadsCaching with TTLNetwork fallback handlingRegistry Explorer[Python] Package discoverySearch capabilitiesRegistry metadata parsingDependencyOrchestrator[Python] Multi-type dependencycoordinationInstallation planningProgress reportingInstallation Context[Python] Installation statemanagementEnvironment isolationProgress trackingInstaller Base[Python] Common installer interfaceError handling patternsResult aggregationPython Installer[Python] Pip package installationConda environmentintegrationSystem Installer[Python] System package installationPrivilege managementAPT/package managerintegrationDocker Installer[Python] Docker image managementRegistry authenticationImage version handlingHatch Installer[Python] Hatch packagedependenciesRecursive installationPackage registrationHatch Validator[Python] Schema validationPackage compliancecheckingMetadata verificationConda/Mamba[Environment Manager] Python environmentcreationPackage managementDocker Engine[Container Runtime] Image managementContainer executionSystem PackageManagers[OS Tools] APT, YUM, etc.System-level dependenciesPackage Registry[Remote Service] Package repositoryMetadata distributionHatch Schemas[JSON Schema] Package metadata schemaValidation rulesManagesenvironmentsLoads and validatespackagesCreates packagetemplatesDelegates PythonoperationsCoordinatesinstallationsCreates PythonenvironmentsValidates packagesUses schema fortemplatesDownloads packagesSearches packagesManages contextInstalls PythonpackagesInstalls systempackagesInstalls DockerimagesInstalls HatchpackagesImplementsImplementsImplementsImplementsInstalls packages viapipInstalls systempackagesManages DockerimagesLoads dependencypackagesUses validationschemasLegend ▯ component ▯ container boundary  \ No newline at end of file +Hatch Architecture OverviewHatch Architecture OverviewCLI Layer[container]Core Management[container]Package System[container]Registry System[container]Installation System[container]Validation System[container]External Systems[container]CLI Interface[Python] Command-line interfaceArgument parsing andvalidationEnvironment Manager[Python] Environment lifecycleMetadata persistenceCurrent environmenttrackingPython EnvironmentManager[Python] Conda/mamba integrationPython executableresolutionPackage installationcoordinationPackage Loader[Python] Local package inspectionMetadata validationStructure verificationTemplate Generator[Python] Package template creationBoilerplate file generationDefault metadata setupRegistry Retriever[Python] Package downloadsCaching with TTLNetwork fallback handlingRegistry Explorer[Python] Package discoverySearch capabilitiesRegistry metadata parsingDependencyOrchestrator[Python] Multi-type dependencycoordinationInstallation planningProgress reportingInstallation Context[Python] Installation statemanagementEnvironment isolationProgress trackingInstaller Base[Python] Common installer interfaceError handling patternsResult aggregationPython Installer[Python] Pip package installationConda environmentintegrationSystem Installer[Python] System package installationPrivilege managementAPT/package managerintegrationDocker Installer[Python] Docker image managementRegistry authenticationImage version handlingHatch Installer[Python] Hatch packagedependenciesRecursive installationPackage registrationHatch Validator[Python] Schema validationPackage compliancecheckingMetadata verificationConda/Mamba[Environment Manager] Python environmentcreationPackage managementDocker Engine[Container Runtime] Image managementContainer executionSystem PackageManagers[OS Tools] APT, YUM, etc.System-level dependenciesPackage Registry[Remote Service] Package repositoryMetadata distributionHatch Schemas[JSON Schema] Package metadata schemaValidation rulesManagesenvironmentsLoads and validatespackagesCreates packagetemplatesDelegates PythonoperationsCoordinatesinstallationsCreates PythonenvironmentsValidates packagesUses schema fortemplatesDownloads packagesSearches packagesManages contextInstalls PythonpackagesInstalls systempackagesInstalls DockerimagesInstalls HatchpackagesImplementsImplementsImplementsImplementsInstalls packages viapipInstalls systempackagesManages DockerimagesLoads dependencypackagesUses validationschemasLegend ▯ component ▯ container boundary  diff --git a/hatch/__init__.py b/hatch/__init__.py index e7f401b..4a7c3ed 100644 --- a/hatch/__init__.py +++ b/hatch/__init__.py @@ -5,17 +5,17 @@ and interacting with the Hatch registry. """ -from .cli_hatch import main +from .cli import main from .environment_manager import HatchEnvironmentManager from .package_loader import HatchPackageLoader, PackageLoaderError from .registry_retriever import RegistryRetriever from .template_generator import create_package_template __all__ = [ - 'HatchEnvironmentManager', - 'HatchPackageLoader', - 'PackageLoaderError', - 'RegistryRetriever', - 'create_package_template', - 'main', -] \ No newline at end of file + "HatchEnvironmentManager", + "HatchPackageLoader", + "PackageLoaderError", + "RegistryRetriever", + "create_package_template", + "main", +] diff --git a/hatch/cli/__init__.py b/hatch/cli/__init__.py new file mode 100644 index 0000000..a53bd6a --- /dev/null +++ b/hatch/cli/__init__.py @@ -0,0 +1,72 @@ +"""CLI package for Hatch package manager. + +This package provides the command-line interface for Hatch, organized into +domain-specific handler modules following a handler-based architecture pattern. + +Architecture Overview: + The CLI is structured as a routing layer (__main__.py) that delegates to + specialized handler modules. Each handler follows the standardized signature: + (args: Namespace) -> int, where args contains parsed command-line arguments + and the return value is the exit code (0 for success, non-zero for errors). + +Modules: + __main__: Entry point with argument parsing and command routing + cli_utils: Shared utilities, exit codes, and helper functions + cli_mcp: MCP (Model Context Protocol) host configuration handlers + cli_env: Environment management handlers + cli_package: Package management handlers + cli_system: System commands (create, validate) + +Entry Points: + - main(): Primary entry point for the CLI + - python -m hatch.cli: Module execution + - hatch: Console script (when installed via pip) + +Example: + >>> from hatch.cli import main + >>> exit_code = main() # Runs CLI with sys.argv + + >>> from hatch.cli import EXIT_SUCCESS, EXIT_ERROR + >>> return EXIT_SUCCESS if operation_ok else EXIT_ERROR + +Backward Compatibility: + The hatch.cli_hatch module re-exports all public symbols for backward + compatibility with external consumers. +""" + +# Export utilities from cli_utils (no circular import issues) +from hatch.cli.cli_utils import ( + EXIT_SUCCESS, + EXIT_ERROR, + get_hatch_version, + request_confirmation, + parse_env_vars, + parse_header, + parse_input, + parse_host_list, + get_package_mcp_server_config, +) + + +def main(): + """Main entry point - delegates to __main__.main(). + + This provides the hatch.cli.main() interface. + """ + from hatch.cli.__main__ import main as _main + + return _main() + + +__all__ = [ + "main", + "EXIT_SUCCESS", + "EXIT_ERROR", + "get_hatch_version", + "request_confirmation", + "parse_env_vars", + "parse_header", + "parse_input", + "parse_host_list", + "get_package_mcp_server_config", +] diff --git a/hatch/cli/__main__.py b/hatch/cli/__main__.py new file mode 100644 index 0000000..f1d6e98 --- /dev/null +++ b/hatch/cli/__main__.py @@ -0,0 +1,1057 @@ +"""Entry point for Hatch CLI. + +This module provides the main entry point for the Hatch package manager CLI. +It handles argument parsing and routes commands to appropriate handler modules. + +Architecture: + This module implements the routing layer of the CLI architecture: + 1. Parses command-line arguments using argparse + 2. Initializes shared managers (HatchEnvironmentManager, MCPHostConfigurationManager) + 3. Attaches managers to the args namespace for handler access + 4. Routes commands to appropriate handler modules + +Command Structure: + hatch create - Create package template (cli_system) + hatch validate - Validate package (cli_system) + hatch env - Environment management (cli_env) + hatch package - Package management (cli_package) + hatch mcp - MCP host configuration (cli_mcp) + +Entry Points: + - python -m hatch.cli: Module execution via __main__.py + - hatch: Console script defined in pyproject.toml + +Handler Signature: + All handlers follow: (args: Namespace) -> int + - args.env_manager: HatchEnvironmentManager instance + - args.mcp_manager: MCPHostConfigurationManager instance + - Returns: Exit code (0 for success, non-zero for errors) + +Example: + $ hatch --version + $ hatch env list + $ hatch mcp configure claude-desktop my-server --command python +""" + +import argparse +import logging +import sys +from pathlib import Path + +from hatch.cli.cli_utils import get_hatch_version, Color, _colors_enabled + + +class HatchArgumentParser(argparse.ArgumentParser): + """Custom ArgumentParser with formatted error messages. + + Overrides the error() method to format argparse errors with + [ERROR] prefix and bright red color (when colors enabled). + + Reference: R13 Β§4.2.1 (13-error_message_formatting_v0.md) + + Output format: + [ERROR] + + Example: + >>> parser = HatchArgumentParser(description="Test CLI") + >>> parser.parse_args(['--invalid']) + [ERROR] unrecognized arguments: --invalid + """ + + def error(self, message: str) -> None: + """Override to format errors with [ERROR] prefix and color. + + Args: + message: Error message from argparse + + Note: + Preserves exit code 2 (argparse convention). + """ + if _colors_enabled(): + self.exit(2, f"{Color.RED.value}[ERROR]{Color.RESET.value} {message}\n") + else: + self.exit(2, f"[ERROR] {message}\n") + + +def _setup_create_command(subparsers): + """Set up 'hatch create' command parser.""" + create_parser = subparsers.add_parser( + "create", help="Create a new package template" + ) + create_parser.add_argument("name", help="Package name") + create_parser.add_argument( + "--dir", "-d", default=".", help="Target directory (default: current directory)" + ) + create_parser.add_argument( + "--description", "-D", default="", help="Package description" + ) + create_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + + +def _setup_validate_command(subparsers): + """Set up 'hatch validate' command parser.""" + validate_parser = subparsers.add_parser("validate", help="Validate a package") + validate_parser.add_argument("package_dir", help="Path to package directory") + + +def _setup_env_commands(subparsers): + """Set up 'hatch env' command parsers.""" + env_subparsers = subparsers.add_parser( + "env", help="Environment management commands" + ).add_subparsers(dest="env_command", help="Environment command to execute") + + # Create environment command + env_create_parser = env_subparsers.add_parser( + "create", help="Create a new environment" + ) + env_create_parser.add_argument("name", help="Environment name") + env_create_parser.add_argument( + "--description", "-D", default="", help="Environment description" + ) + env_create_parser.add_argument( + "--python-version", help="Python version for the environment (e.g., 3.11, 3.12)" + ) + env_create_parser.add_argument( + "--no-python", + action="store_true", + help="Don't create a Python environment using conda/mamba", + ) + env_create_parser.add_argument( + "--no-hatch-mcp-server", + action="store_true", + help="Don't install hatch_mcp_server wrapper in the new environment", + ) + env_create_parser.add_argument( + "--hatch_mcp_server_tag", + help="Git tag/branch reference for hatch_mcp_server wrapper installation (e.g., 'dev', 'v0.1.0')", + ) + env_create_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + + # Remove environment command + env_remove_parser = env_subparsers.add_parser( + "remove", help="Remove an environment" + ) + env_remove_parser.add_argument("name", help="Environment name") + env_remove_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + env_remove_parser.add_argument( + "--auto-approve", action="store_true", help="Skip confirmation prompt" + ) + + # List environments command - now with subcommands per R10 + env_list_parser = env_subparsers.add_parser( + "list", help="List environments, hosts, or servers" + ) + env_list_subparsers = env_list_parser.add_subparsers( + dest="list_command", help="List command to execute" + ) + + # Default list behavior (no subcommand) - handled by checking list_command is None + env_list_parser.add_argument( + "--pattern", + help="Filter environments by name using regex pattern", + ) + env_list_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # env list hosts subcommand per R10 Β§3.3 + env_list_hosts_parser = env_list_subparsers.add_parser( + "hosts", help="List environment/host/server deployments" + ) + env_list_hosts_parser.add_argument( + "--env", + "-e", + help="Filter by environment name using regex pattern", + ) + env_list_hosts_parser.add_argument( + "--server", + help="Filter by server name using regex pattern", + ) + env_list_hosts_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # env list servers subcommand per R10 Β§3.4 + env_list_servers_parser = env_list_subparsers.add_parser( + "servers", help="List environment/server/host deployments" + ) + env_list_servers_parser.add_argument( + "--env", + "-e", + help="Filter by environment name using regex pattern", + ) + env_list_servers_parser.add_argument( + "--host", + help="Filter by host name using regex pattern (use '-' for undeployed)", + ) + env_list_servers_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # Set current environment command + env_use_parser = env_subparsers.add_parser( + "use", help="Set the current environment" + ) + env_use_parser.add_argument("name", help="Environment name") + env_use_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + + # Show current environment command + env_subparsers.add_parser("current", help="Show the current environment") + + # Show environment details command + env_show_parser = env_subparsers.add_parser( + "show", help="Show detailed environment configuration" + ) + env_show_parser.add_argument("name", help="Environment name to show") + + # Python environment management commands + env_python_subparsers = env_subparsers.add_parser( + "python", help="Manage Python environments" + ).add_subparsers( + dest="python_command", help="Python environment command to execute" + ) + + # Initialize Python environment + python_init_parser = env_python_subparsers.add_parser( + "init", help="Initialize Python environment" + ) + python_init_parser.add_argument( + "--hatch_env", + default=None, + help="Hatch environment name in which the Python environment is located (default: current environment)", + ) + python_init_parser.add_argument( + "--python-version", help="Python version (e.g., 3.11, 3.12)" + ) + python_init_parser.add_argument( + "--force", action="store_true", help="Force recreation if exists" + ) + python_init_parser.add_argument( + "--no-hatch-mcp-server", + action="store_true", + help="Don't install hatch_mcp_server wrapper in the Python environment", + ) + python_init_parser.add_argument( + "--hatch_mcp_server_tag", + help="Git tag/branch reference for hatch_mcp_server wrapper installation (e.g., 'dev', 'v0.1.0')", + ) + python_init_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + + # Show Python environment info + python_info_parser = env_python_subparsers.add_parser( + "info", help="Show Python environment information" + ) + python_info_parser.add_argument( + "--hatch_env", + default=None, + help="Hatch environment name in which the Python environment is located (default: current environment)", + ) + python_info_parser.add_argument( + "--detailed", action="store_true", help="Show detailed diagnostics" + ) + + # Hatch MCP server wrapper management + hatch_mcp_parser = env_python_subparsers.add_parser( + "add-hatch-mcp", help="Add hatch_mcp_server wrapper to the environment" + ) + hatch_mcp_parser.add_argument( + "--hatch_env", + default=None, + help="Hatch environment name. It must possess a valid Python environment. (default: current environment)", + ) + hatch_mcp_parser.add_argument( + "--tag", + default=None, + help="Git tag/branch reference for wrapper installation (e.g., 'dev', 'v0.1.0')", + ) + hatch_mcp_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + + # Remove Python environment + python_remove_parser = env_python_subparsers.add_parser( + "remove", help="Remove Python environment" + ) + python_remove_parser.add_argument( + "--hatch_env", + default=None, + help="Hatch environment name in which the Python environment is located (default: current environment)", + ) + python_remove_parser.add_argument( + "--force", action="store_true", help="Force removal without confirmation" + ) + python_remove_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + + # Launch Python shell + python_shell_parser = env_python_subparsers.add_parser( + "shell", help="Launch Python shell in environment" + ) + python_shell_parser.add_argument( + "--hatch_env", + default=None, + help="Hatch environment name in which the Python environment is located (default: current environment)", + ) + python_shell_parser.add_argument( + "--cmd", help="Command to run in the shell (optional)" + ) + + +def _setup_package_commands(subparsers): + """Set up 'hatch package' command parsers.""" + pkg_subparsers = subparsers.add_parser( + "package", help="Package management commands" + ).add_subparsers(dest="pkg_command", help="Package command to execute") + + # Add package command + pkg_add_parser = pkg_subparsers.add_parser( + "add", help="Add a package to the current environment" + ) + pkg_add_parser.add_argument( + "package_path_or_name", help="Path to package directory or name of the package" + ) + pkg_add_parser.add_argument( + "--env", + "-e", + default=None, + help="Environment name (default: current environment)", + ) + pkg_add_parser.add_argument( + "--version", "-v", default=None, help="Version of the package (optional)" + ) + pkg_add_parser.add_argument( + "--force-download", + "-f", + action="store_true", + help="Force download even if package is in cache", + ) + pkg_add_parser.add_argument( + "--refresh-registry", + "-r", + action="store_true", + help="Force refresh of registry data", + ) + pkg_add_parser.add_argument( + "--auto-approve", + action="store_true", + help="Automatically approve changes installation of deps for automation scenario", + ) + pkg_add_parser.add_argument( + "--host", + help="Comma-separated list of MCP host platforms to configure (e.g., claude-desktop,cursor)", + ) + pkg_add_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + + # Remove package command + pkg_remove_parser = pkg_subparsers.add_parser( + "remove", help="Remove a package from the current environment" + ) + pkg_remove_parser.add_argument("package_name", help="Name of the package to remove") + pkg_remove_parser.add_argument( + "--env", + "-e", + default=None, + help="Environment name (default: current environment)", + ) + pkg_remove_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + pkg_remove_parser.add_argument( + "--auto-approve", action="store_true", help="Skip confirmation prompt" + ) + + # List packages command + pkg_list_parser = pkg_subparsers.add_parser( + "list", help="List packages in an environment" + ) + pkg_list_parser.add_argument( + "--env", "-e", help="Environment name (default: current environment)" + ) + + # Sync package MCP servers command + pkg_sync_parser = pkg_subparsers.add_parser( + "sync", help="Synchronize package MCP servers to host platforms" + ) + pkg_sync_parser.add_argument( + "package_name", help="Name of the package whose MCP servers to sync" + ) + pkg_sync_parser.add_argument( + "--host", + required=True, + help="Comma-separated list of host platforms to sync to (or 'all')", + ) + pkg_sync_parser.add_argument( + "--env", + "-e", + default=None, + help="Environment name (default: current environment)", + ) + pkg_sync_parser.add_argument( + "--dry-run", action="store_true", help="Preview changes without execution" + ) + pkg_sync_parser.add_argument( + "--auto-approve", action="store_true", help="Skip confirmation prompts" + ) + pkg_sync_parser.add_argument( + "--no-backup", action="store_true", help="Disable default backup behavior" + ) + + +def _setup_mcp_commands(subparsers): + """Set up 'hatch mcp' command parsers.""" + mcp_subparsers = subparsers.add_parser( + "mcp", help="MCP host configuration commands" + ).add_subparsers(dest="mcp_command", help="MCP command to execute") + + # MCP discovery commands + mcp_discover_subparsers = mcp_subparsers.add_parser( + "discover", help="Discover MCP hosts and servers" + ).add_subparsers(dest="discover_command", help="Discovery command to execute") + + # Discover hosts command + mcp_discover_hosts_parser = mcp_discover_subparsers.add_parser( + "hosts", help="Discover available MCP host platforms" + ) + mcp_discover_hosts_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # Discover servers command + mcp_discover_servers_parser = mcp_discover_subparsers.add_parser( + "servers", help="Discover configured MCP servers" + ) + mcp_discover_servers_parser.add_argument( + "--env", + "-e", + default=None, + help="Environment name (default: current environment)", + ) + + # MCP list commands + mcp_list_subparsers = mcp_subparsers.add_parser( + "list", help="List MCP hosts and servers" + ).add_subparsers(dest="list_command", help="List command to execute") + + # List hosts command - host-centric design per R10 Β§3.1 + mcp_list_hosts_parser = mcp_list_subparsers.add_parser( + "hosts", help="List host/server pairs from host configuration files" + ) + mcp_list_hosts_parser.add_argument( + "--server", + help="Filter by server name using regex pattern", + ) + mcp_list_hosts_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # List servers command - per R10 Β§3.2 (--pattern removed, use mcp list hosts --server instead) + mcp_list_servers_parser = mcp_list_subparsers.add_parser( + "servers", help="List server/host pairs from host configuration files" + ) + mcp_list_servers_parser.add_argument( + "--host", + help="Filter by host name using regex pattern", + ) + mcp_list_servers_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # MCP show commands (detailed views) - per R11 specification + mcp_show_subparsers = mcp_subparsers.add_parser( + "show", help="Show detailed MCP host or server configuration" + ).add_subparsers(dest="show_command", help="Show command to execute") + + # Show hosts command - host-centric detailed view per R11 Β§2.1 + mcp_show_hosts_parser = mcp_show_subparsers.add_parser( + "hosts", help="Show detailed host configurations" + ) + mcp_show_hosts_parser.add_argument( + "--server", + help="Filter by server name using regex pattern", + ) + mcp_show_hosts_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # Show servers command - server-centric detailed view per R11 Β§2.2 + mcp_show_servers_parser = mcp_show_subparsers.add_parser( + "servers", help="Show detailed server configurations across hosts" + ) + mcp_show_servers_parser.add_argument( + "--host", + help="Filter by host name using regex pattern", + ) + mcp_show_servers_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # MCP backup commands + mcp_backup_subparsers = mcp_subparsers.add_parser( + "backup", help="Backup management commands" + ).add_subparsers(dest="backup_command", help="Backup command to execute") + + # Restore backup command + mcp_backup_restore_parser = mcp_backup_subparsers.add_parser( + "restore", help="Restore MCP host configuration from backup" + ) + mcp_backup_restore_parser.add_argument( + "host", help="Host platform to restore (e.g., claude-desktop, cursor)" + ) + mcp_backup_restore_parser.add_argument( + "--backup-file", + "-f", + default=None, + help="Specific backup file to restore (default: latest)", + ) + mcp_backup_restore_parser.add_argument( + "--dry-run", + action="store_true", + help="Preview restore operation without execution", + ) + mcp_backup_restore_parser.add_argument( + "--auto-approve", action="store_true", help="Skip confirmation prompts" + ) + + # List backups command + mcp_backup_list_parser = mcp_backup_subparsers.add_parser( + "list", help="List available backups for MCP host" + ) + mcp_backup_list_parser.add_argument( + "host", help="Host platform to list backups for (e.g., claude-desktop, cursor)" + ) + mcp_backup_list_parser.add_argument( + "--detailed", "-d", action="store_true", help="Show detailed backup information" + ) + mcp_backup_list_parser.add_argument( + "--json", action="store_true", help="Output in JSON format" + ) + + # Clean backups command + mcp_backup_clean_parser = mcp_backup_subparsers.add_parser( + "clean", help="Clean old backups based on criteria" + ) + mcp_backup_clean_parser.add_argument( + "host", help="Host platform to clean backups for (e.g., claude-desktop, cursor)" + ) + mcp_backup_clean_parser.add_argument( + "--older-than-days", type=int, help="Remove backups older than specified days" + ) + mcp_backup_clean_parser.add_argument( + "--keep-count", + type=int, + help="Keep only the specified number of newest backups", + ) + mcp_backup_clean_parser.add_argument( + "--dry-run", + action="store_true", + help="Preview cleanup operation without execution", + ) + mcp_backup_clean_parser.add_argument( + "--auto-approve", action="store_true", help="Skip confirmation prompts" + ) + + # MCP configure command + mcp_configure_parser = mcp_subparsers.add_parser( + "configure", help="Configure MCP server directly on host" + ) + mcp_configure_parser.add_argument( + "server_name", help="Name for the MCP server [hosts: all]" + ) + mcp_configure_parser.add_argument( + "--host", + required=True, + help="Host platform to configure (e.g., claude-desktop, cursor) [hosts: all]", + ) + + # Create mutually exclusive group for server type + server_type_group = mcp_configure_parser.add_mutually_exclusive_group() + server_type_group.add_argument( + "--command", + dest="server_command", + help="Command to execute the MCP server (for local servers) [hosts: all]", + ) + server_type_group.add_argument( + "--url", + help="Server URL for remote MCP servers (SSE transport) [hosts: all except claude-desktop, claude-code]", + ) + server_type_group.add_argument( + "--http-url", help="HTTP streaming endpoint URL [hosts: gemini]" + ) + + mcp_configure_parser.add_argument( + "--args", + nargs="*", + help="Arguments for the MCP server command (only with --command) [hosts: all]", + ) + mcp_configure_parser.add_argument( + "--env-var", + action="append", + help="Environment variables (format: KEY=VALUE) [hosts: all]", + ) + mcp_configure_parser.add_argument( + "--header", + action="append", + help="HTTP headers for remote servers (format: KEY=VALUE, only with --url) [hosts: all except claude-desktop, claude-code]", + ) + + # Host-specific arguments (Gemini) + mcp_configure_parser.add_argument( + "--timeout", type=int, help="Request timeout in milliseconds [hosts: gemini]" + ) + mcp_configure_parser.add_argument( + "--trust", + action="store_true", + help="Bypass tool call confirmations [hosts: gemini]", + ) + mcp_configure_parser.add_argument( + "--cwd", help="Working directory for stdio transport [hosts: gemini, codex]" + ) + mcp_configure_parser.add_argument( + "--include-tools", + nargs="*", + help="Tool allowlist / enabled tools [hosts: gemini, codex]", + ) + mcp_configure_parser.add_argument( + "--exclude-tools", + nargs="*", + help="Tool blocklist / disabled tools [hosts: gemini, codex]", + ) + + # Host-specific arguments (Cursor/VS Code/LM Studio) + mcp_configure_parser.add_argument( + "--env-file", help="Path to environment file [hosts: cursor, vscode, lmstudio]" + ) + + # Host-specific arguments (VS Code) + mcp_configure_parser.add_argument( + "--input", + action="append", + help="Input variable definitions in format: type,id,description[,password=true] [hosts: vscode]", + ) + + # Host-specific arguments (Kiro) + mcp_configure_parser.add_argument( + "--disabled", + action="store_true", + default=None, + help="Disable the MCP server [hosts: kiro]", + ) + mcp_configure_parser.add_argument( + "--auto-approve-tools", + action="append", + help="Tool names to auto-approve without prompting [hosts: kiro]", + ) + mcp_configure_parser.add_argument( + "--disable-tools", action="append", help="Tool names to disable [hosts: kiro]" + ) + + # Codex-specific arguments + mcp_configure_parser.add_argument( + "--env-vars", + action="append", + help="Environment variable names to whitelist/forward [hosts: codex]", + ) + mcp_configure_parser.add_argument( + "--startup-timeout", + type=int, + help="Server startup timeout in seconds (default: 10) [hosts: codex]", + ) + mcp_configure_parser.add_argument( + "--tool-timeout", + type=int, + help="Tool execution timeout in seconds (default: 60) [hosts: codex]", + ) + mcp_configure_parser.add_argument( + "--enabled", + action="store_true", + default=None, + help="Enable the MCP server [hosts: codex]", + ) + mcp_configure_parser.add_argument( + "--bearer-token-env-var", + type=str, + help="Name of environment variable containing bearer token for Authorization header [hosts: codex]", + ) + mcp_configure_parser.add_argument( + "--env-header", + action="append", + help="HTTP header from environment variable in KEY=ENV_VAR_NAME format [hosts: codex]", + ) + + mcp_configure_parser.add_argument( + "--no-backup", + action="store_true", + help="Skip backup creation before configuration [hosts: all]", + ) + mcp_configure_parser.add_argument( + "--dry-run", + action="store_true", + help="Preview configuration without execution [hosts: all]", + ) + mcp_configure_parser.add_argument( + "--auto-approve", + action="store_true", + help="Skip confirmation prompts [hosts: all]", + ) + + # MCP remove commands + mcp_remove_subparsers = mcp_subparsers.add_parser( + "remove", help="Remove MCP servers or host configurations" + ).add_subparsers(dest="remove_command", help="Remove command to execute") + + # Remove server command + mcp_remove_server_parser = mcp_remove_subparsers.add_parser( + "server", help="Remove MCP server from hosts" + ) + mcp_remove_server_parser.add_argument( + "server_name", help="Name of the MCP server to remove" + ) + mcp_remove_server_parser.add_argument( + "--host", help="Target hosts (comma-separated or 'all')" + ) + mcp_remove_server_parser.add_argument( + "--env", "-e", help="Environment name (for environment-based removal)" + ) + mcp_remove_server_parser.add_argument( + "--no-backup", action="store_true", help="Skip backup creation before removal" + ) + mcp_remove_server_parser.add_argument( + "--dry-run", action="store_true", help="Preview removal without execution" + ) + mcp_remove_server_parser.add_argument( + "--auto-approve", action="store_true", help="Skip confirmation prompts" + ) + + # Remove host command + mcp_remove_host_parser = mcp_remove_subparsers.add_parser( + "host", help="Remove entire host configuration" + ) + mcp_remove_host_parser.add_argument( + "host_name", help="Host platform to remove (e.g., claude-desktop, cursor)" + ) + mcp_remove_host_parser.add_argument( + "--no-backup", action="store_true", help="Skip backup creation before removal" + ) + mcp_remove_host_parser.add_argument( + "--dry-run", action="store_true", help="Preview removal without execution" + ) + mcp_remove_host_parser.add_argument( + "--auto-approve", action="store_true", help="Skip confirmation prompts" + ) + + # MCP sync command + mcp_sync_parser = mcp_subparsers.add_parser( + "sync", help="Synchronize MCP configurations between environments and hosts" + ) + + # Source options (mutually exclusive) + sync_source_group = mcp_sync_parser.add_mutually_exclusive_group(required=True) + sync_source_group.add_argument("--from-env", help="Source environment name") + sync_source_group.add_argument("--from-host", help="Source host platform") + + # Target options + mcp_sync_parser.add_argument( + "--to-host", required=True, help="Target hosts (comma-separated or 'all')" + ) + + # Filter options (mutually exclusive) + sync_filter_group = mcp_sync_parser.add_mutually_exclusive_group() + sync_filter_group.add_argument( + "--servers", help="Specific server names to sync (comma-separated)" + ) + sync_filter_group.add_argument( + "--pattern", help="Regex pattern for server selection" + ) + + # Standard options + mcp_sync_parser.add_argument( + "--dry-run", + action="store_true", + help="Preview synchronization without execution", + ) + mcp_sync_parser.add_argument( + "--auto-approve", action="store_true", help="Skip confirmation prompts" + ) + mcp_sync_parser.add_argument( + "--no-backup", + action="store_true", + help="Skip backup creation before synchronization", + ) + mcp_sync_parser.add_argument( + "--detailed", + nargs="?", + const="all", + default=None, + help="Show field-level details (optionally filter by consequence types: created,updated,synced,etc. or 'all')", + ) + + +def _route_env_command(args): + """Route environment commands to handlers.""" + from hatch.cli.cli_env import ( + handle_env_create, + handle_env_remove, + handle_env_list, + handle_env_list_hosts, + handle_env_list_servers, + handle_env_use, + handle_env_current, + handle_env_show, + handle_env_python_init, + handle_env_python_info, + handle_env_python_remove, + handle_env_python_shell, + handle_env_python_add_hatch_mcp, + ) + + if args.env_command == "create": + return handle_env_create(args) + elif args.env_command == "remove": + return handle_env_remove(args) + elif args.env_command == "list": + # Check for subcommand (hosts, servers) or default list behavior + list_command = getattr(args, "list_command", None) + if list_command == "hosts": + return handle_env_list_hosts(args) + elif list_command == "servers": + return handle_env_list_servers(args) + else: + # Default: list environments + return handle_env_list(args) + elif args.env_command == "use": + return handle_env_use(args) + elif args.env_command == "current": + return handle_env_current(args) + elif args.env_command == "show": + return handle_env_show(args) + elif args.env_command == "python": + if args.python_command == "init": + return handle_env_python_init(args) + elif args.python_command == "info": + return handle_env_python_info(args) + elif args.python_command == "remove": + return handle_env_python_remove(args) + elif args.python_command == "shell": + return handle_env_python_shell(args) + elif args.python_command == "add-hatch-mcp": + return handle_env_python_add_hatch_mcp(args) + else: + print("Unknown Python environment command") + return 1 + else: + print("Unknown environment command") + return 1 + + +def _route_package_command(args): + """Route package commands to handlers.""" + from hatch.cli.cli_package import ( + handle_package_add, + handle_package_remove, + handle_package_list, + handle_package_sync, + ) + + if args.pkg_command == "add": + return handle_package_add(args) + elif args.pkg_command == "remove": + return handle_package_remove(args) + elif args.pkg_command == "list": + return handle_package_list(args) + elif args.pkg_command == "sync": + return handle_package_sync(args) + else: + print("Unknown package command") + return 1 + + +def _route_mcp_command(args): + """Route MCP commands to handlers.""" + from hatch.cli.cli_mcp import ( + handle_mcp_discover_hosts, + handle_mcp_discover_servers, + handle_mcp_list_hosts, + handle_mcp_list_servers, + handle_mcp_show_hosts, + handle_mcp_show_servers, + handle_mcp_backup_restore, + handle_mcp_backup_list, + handle_mcp_backup_clean, + handle_mcp_configure, + handle_mcp_remove_server, + handle_mcp_remove_host, + handle_mcp_sync, + ) + + if args.mcp_command == "discover": + if args.discover_command == "hosts": + return handle_mcp_discover_hosts(args) + elif args.discover_command == "servers": + return handle_mcp_discover_servers(args) + else: + print("Unknown discover command") + return 1 + + elif args.mcp_command == "list": + if args.list_command == "hosts": + return handle_mcp_list_hosts(args) + elif args.list_command == "servers": + return handle_mcp_list_servers(args) + else: + print("Unknown list command") + return 1 + + elif args.mcp_command == "show": + show_command = getattr(args, "show_command", None) + if show_command == "hosts": + return handle_mcp_show_hosts(args) + elif show_command == "servers": + return handle_mcp_show_servers(args) + else: + print( + "Unknown show command. Use 'hatch mcp show hosts' or 'hatch mcp show servers'" + ) + return 1 + + elif args.mcp_command == "backup": + if args.backup_command == "restore": + return handle_mcp_backup_restore(args) + elif args.backup_command == "list": + return handle_mcp_backup_list(args) + elif args.backup_command == "clean": + return handle_mcp_backup_clean(args) + else: + print("Unknown backup command") + return 1 + + elif args.mcp_command == "configure": + return handle_mcp_configure(args) + + elif args.mcp_command == "remove": + if args.remove_command == "server": + return handle_mcp_remove_server(args) + elif args.remove_command == "host": + return handle_mcp_remove_host(args) + else: + print("Unknown remove command") + return 1 + + elif args.mcp_command == "sync": + return handle_mcp_sync(args) + + else: + print("Unknown MCP command") + return 1 + + +def main() -> int: + """Main entry point for Hatch CLI. + + Parses command-line arguments and routes to appropriate handlers for: + - Package template creation + - Package validation + - Environment management + - Package management + - MCP host configuration + + Returns: + int: Exit code (0 for success, 1 for errors) + """ + # Configure logging + logging.basicConfig( + level=logging.INFO, + format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", + ) + + # Create argument parser + parser = HatchArgumentParser(description="Hatch package manager CLI") + + # Add version argument + parser.add_argument( + "--version", action="version", version=f"%(prog)s {get_hatch_version()}" + ) + + subparsers = parser.add_subparsers(dest="command", help="Command to execute") + + # Set up command parsers + _setup_create_command(subparsers) + _setup_validate_command(subparsers) + _setup_env_commands(subparsers) + _setup_package_commands(subparsers) + _setup_mcp_commands(subparsers) + + # General arguments for the environment manager + parser.add_argument( + "--envs-dir", + default=Path.home() / ".hatch" / "envs", + help="Directory to store environments", + ) + parser.add_argument( + "--cache-ttl", + type=int, + default=86400, + help="Cache TTL in seconds (default: 86400 seconds --> 1 day)", + ) + parser.add_argument( + "--cache-dir", + default=Path.home() / ".hatch" / "cache", + help="Directory to store cached packages", + ) + + args = parser.parse_args() + + # Initialize managers (lazy - only when needed) + from hatch.environment_manager import HatchEnvironmentManager + from hatch.mcp_host_config import MCPHostConfigurationManager + + env_manager = HatchEnvironmentManager( + environments_dir=args.envs_dir, + cache_ttl=args.cache_ttl, + cache_dir=args.cache_dir, + ) + mcp_manager = MCPHostConfigurationManager() + + # Attach managers to args for handler access + args.env_manager = env_manager + args.mcp_manager = mcp_manager + + # Route commands + if args.command == "create": + from hatch.cli.cli_system import handle_create + + return handle_create(args) + + elif args.command == "validate": + from hatch.cli.cli_system import handle_validate + + return handle_validate(args) + + elif args.command == "env": + return _route_env_command(args) + + elif args.command == "package": + return _route_package_command(args) + + elif args.command == "mcp": + return _route_mcp_command(args) + + else: + parser.print_help() + return 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/hatch/cli/cli_env.py b/hatch/cli/cli_env.py new file mode 100644 index 0000000..91a8d12 --- /dev/null +++ b/hatch/cli/cli_env.py @@ -0,0 +1,901 @@ +"""Environment CLI handlers for Hatch. + +This module contains handlers for environment management commands. Environments +provide isolated contexts for managing packages and their MCP server configurations. + +Commands: + Basic Environment Management: + - hatch env create : Create a new environment + - hatch env remove : Remove an environment + - hatch env list: List all environments + - hatch env use : Set current environment + - hatch env current: Show current environment + + Python Environment Management: + - hatch env python init: Initialize Python virtual environment + - hatch env python info: Show Python environment info + - hatch env python remove: Remove Python virtual environment + - hatch env python shell: Launch interactive Python shell + - hatch env python add-hatch-mcp: Add hatch_mcp_server wrapper script + +Handler Signature: + All handlers follow: (args: Namespace) -> int + - args.env_manager: HatchEnvironmentManager instance + - Returns: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + +Example: + $ hatch env create my-project + $ hatch env use my-project + $ hatch env python init + $ hatch env python shell +""" + +from argparse import Namespace +from typing import TYPE_CHECKING + +from hatch.cli.cli_utils import ( + EXIT_SUCCESS, + EXIT_ERROR, + request_confirmation, + ResultReporter, + ConsequenceType, + TableFormatter, + ColumnDef, + ValidationError, + format_validation_error, + format_info, +) + +if TYPE_CHECKING: + from hatch.environment_manager import HatchEnvironmentManager + + +def handle_env_create(args: Namespace) -> int: + """Handle 'hatch env create' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - name: Environment name + - description: Environment description + - python_version: Optional Python version + - no_python: Skip Python environment creation + - no_hatch_mcp_server: Skip hatch_mcp_server installation + - hatch_mcp_server_tag: Git tag for hatch_mcp_server + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + name = args.name + description = getattr(args, "description", "") + python_version = getattr(args, "python_version", None) + create_python_env = not getattr(args, "no_python", False) + no_hatch_mcp_server = getattr(args, "no_hatch_mcp_server", False) + hatch_mcp_server_tag = getattr(args, "hatch_mcp_server_tag", None) + dry_run = getattr(args, "dry_run", False) + + # Create reporter for unified output + reporter = ResultReporter("hatch env create", dry_run=dry_run) + reporter.add(ConsequenceType.CREATE, f"Environment '{name}'") + + if create_python_env: + version_str = f" ({python_version})" if python_version else "" + reporter.add(ConsequenceType.CREATE, f"Python environment{version_str}") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + if env_manager.create_environment( + name, + description, + python_version=python_version, + create_python_env=create_python_env, + no_hatch_mcp_server=no_hatch_mcp_server, + hatch_mcp_server_tag=hatch_mcp_server_tag, + ): + # Update reporter with actual Python environment details + if create_python_env and env_manager.is_python_environment_available(): + python_exec = env_manager.python_env_manager.get_python_executable(name) + if python_exec: + # Get Python version for potential future use + # python_version_info = env_manager.python_env_manager.get_python_version(name) + # Add details as child consequences would be ideal, but for now just report success + pass + + reporter.report_result() + return EXIT_SUCCESS + else: + reporter.report_error(f"Failed to create environment '{name}'") + return EXIT_ERROR + + +def handle_env_remove(args: Namespace) -> int: + """Handle 'hatch env remove' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - name: Environment name to remove + - dry_run: Preview changes without execution + - auto_approve: Skip confirmation prompt + + Returns: + Exit code (0 for success, 1 for error) + + Reference: R03 Β§3.1 (03-mutation_output_specification_v0.md) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + name = args.name + dry_run = getattr(args, "dry_run", False) + auto_approve = getattr(args, "auto_approve", False) + + # Create reporter for unified output + reporter = ResultReporter("hatch env remove", dry_run=dry_run) + reporter.add(ConsequenceType.REMOVE, f"Environment '{name}'") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt and request confirmation unless auto-approved + if not auto_approve: + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + if not request_confirmation("Proceed?"): + format_info("Operation cancelled") + return EXIT_SUCCESS + + if env_manager.remove_environment(name): + reporter.report_result() + return EXIT_SUCCESS + else: + reporter.report_error(f"Failed to remove environment '{name}'") + return EXIT_ERROR + + +def handle_env_list(args: Namespace) -> int: + """Handle 'hatch env list' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - pattern: Optional regex pattern to filter environments + - json: Optional flag for JSON output + + Returns: + Exit code (0 for success) + + Reference: R02 Β§2.1 (02-list_output_format_specification_v2.md) + """ + import json as json_module + import re + + env_manager: "HatchEnvironmentManager" = args.env_manager + json_output: bool = getattr(args, "json", False) + pattern: str = getattr(args, "pattern", None) + environments = env_manager.list_environments() + + # Apply pattern filter if specified + if pattern: + try: + regex = re.compile(pattern) + environments = [ + env for env in environments if regex.search(env.get("name", "")) + ] + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid regex pattern: {e}", + field="--pattern", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + if json_output: + # JSON output per R02 Β§8.1 + env_data = [] + for env in environments: + env_name = env.get("name") + python_version = None + if env.get("python_environment", False): + python_info = env_manager.get_python_environment_info(env_name) + if python_info: + python_version = python_info.get("python_version") + + packages_list = env_manager.list_packages(env_name) + pkg_names = [pkg["name"] for pkg in packages_list] if packages_list else [] + + env_data.append( + { + "name": env_name, + "is_current": env.get("is_current", False), + "python_version": python_version, + "packages": pkg_names, + } + ) + + print(json_module.dumps({"environments": env_data}, indent=2)) + return EXIT_SUCCESS + + # Table output + print("Environments:") + + # Define table columns per R10 Β§5.1 (simplified output - count only) + columns = [ + ColumnDef(name="Name", width=15), + ColumnDef(name="Python", width=10), + ColumnDef(name="Packages", width=10, align="right"), + ] + formatter = TableFormatter(columns) + + for env in environments: + # Name with current marker + current_marker = "* " if env.get("is_current") else " " + name = f"{current_marker}{env.get('name')}" + + # Python version + python_version = "-" + if env.get("python_environment", False): + python_info = env_manager.get_python_environment_info(env.get("name")) + if python_info: + python_version = python_info.get("python_version", "Unknown") + + # Packages - show count only per R10 Β§5.1 + packages_list = env_manager.list_packages(env.get("name")) + packages_count = str(len(packages_list)) if packages_list else "0" + + formatter.add_row([name, python_version, packages_count]) + + print(formatter.render()) + return EXIT_SUCCESS + + +def handle_env_use(args: Namespace) -> int: + """Handle 'hatch env use' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - name: Environment name to set as current + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + name = args.name + dry_run = getattr(args, "dry_run", False) + + # Create reporter for unified output + reporter = ResultReporter("hatch env use", dry_run=dry_run) + reporter.add(ConsequenceType.SET, f"Current environment β†’ '{name}'") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + if env_manager.set_current_environment(name): + reporter.report_result() + return EXIT_SUCCESS + else: + reporter.report_error(f"Failed to set environment '{name}'") + return EXIT_ERROR + + +def handle_env_current(args: Namespace) -> int: + """Handle 'hatch env current' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + + Returns: + Exit code (0 for success) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + current_env = env_manager.get_current_environment() + print(f"Current environment: {current_env}") + return EXIT_SUCCESS + + +def handle_env_python_init(args: Namespace) -> int: + """Handle 'hatch env python init' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - hatch_env: Optional environment name (default: current) + - python_version: Optional Python version + - force: Force recreation if exists + - no_hatch_mcp_server: Skip hatch_mcp_server installation + - hatch_mcp_server_tag: Git tag for hatch_mcp_server + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + hatch_env = getattr(args, "hatch_env", None) + python_version = getattr(args, "python_version", None) + force = getattr(args, "force", False) + no_hatch_mcp_server = getattr(args, "no_hatch_mcp_server", False) + hatch_mcp_server_tag = getattr(args, "hatch_mcp_server_tag", None) + dry_run = getattr(args, "dry_run", False) + + env_name = hatch_env or env_manager.get_current_environment() + + # Create reporter for unified output + reporter = ResultReporter("hatch env python init", dry_run=dry_run) + version_str = f" ({python_version})" if python_version else "" + reporter.add( + ConsequenceType.INITIALIZE, f"Python environment for '{env_name}'{version_str}" + ) + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + if env_manager.create_python_environment_only( + hatch_env, + python_version, + force, + no_hatch_mcp_server=no_hatch_mcp_server, + hatch_mcp_server_tag=hatch_mcp_server_tag, + ): + reporter.report_result() + return EXIT_SUCCESS + else: + reporter.report_error( + f"Failed to initialize Python environment for '{env_name}'" + ) + return EXIT_ERROR + + +def handle_env_python_info(args: Namespace) -> int: + """Handle 'hatch env python info' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - hatch_env: Optional environment name (default: current) + - detailed: Show detailed diagnostics + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + hatch_env = getattr(args, "hatch_env", None) + detailed = getattr(args, "detailed", False) + + python_info = env_manager.get_python_environment_info(hatch_env) + + if python_info: + env_name = hatch_env or env_manager.get_current_environment() + print(f"Python environment info for '{env_name}':") + print( + f" Status: {'Active' if python_info.get('enabled', False) else 'Inactive'}" + ) + print(f" Python executable: {python_info['python_executable']}") + print(f" Python version: {python_info.get('python_version', 'Unknown')}") + print(f" Conda environment: {python_info.get('conda_env_name', 'N/A')}") + print(f" Environment path: {python_info['environment_path']}") + print(f" Created: {python_info.get('created_at', 'Unknown')}") + print(f" Package count: {python_info.get('package_count', 0)}") + print(" Packages:") + for pkg in python_info.get("packages", []): + print(f" - {pkg['name']} ({pkg['version']})") + + if detailed: + print("\nDiagnostics:") + diagnostics = env_manager.get_python_environment_diagnostics(hatch_env) + if diagnostics: + for key, value in diagnostics.items(): + print(f" {key}: {value}") + else: + print(" No diagnostics available") + + return EXIT_SUCCESS + else: + env_name = hatch_env or env_manager.get_current_environment() + print(f"No Python environment found for: {env_name}") + + # Show diagnostics for missing environment + if detailed: + print("\nDiagnostics:") + general_diagnostics = env_manager.get_python_manager_diagnostics() + for key, value in general_diagnostics.items(): + print(f" {key}: {value}") + + return EXIT_ERROR + + +def handle_env_python_remove(args: Namespace) -> int: + """Handle 'hatch env python remove' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - hatch_env: Optional environment name (default: current) + - force: Skip confirmation prompt + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + hatch_env = getattr(args, "hatch_env", None) + force = getattr(args, "force", False) + dry_run = getattr(args, "dry_run", False) + + env_name = hatch_env or env_manager.get_current_environment() + + # Create reporter for unified output + reporter = ResultReporter("hatch env python remove", dry_run=dry_run) + reporter.add(ConsequenceType.REMOVE, f"Python environment for '{env_name}'") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + if not force: + # Ask for confirmation using TTY-aware function + if not request_confirmation(f"Remove Python environment for '{env_name}'?"): + format_info("Operation cancelled") + return EXIT_SUCCESS + + if env_manager.remove_python_environment_only(hatch_env): + reporter.report_result() + return EXIT_SUCCESS + else: + reporter.report_error(f"Failed to remove Python environment from '{env_name}'") + return EXIT_ERROR + + +def handle_env_python_shell(args: Namespace) -> int: + """Handle 'hatch env python shell' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - hatch_env: Optional environment name (default: current) + - cmd: Optional command to run in shell + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + hatch_env = getattr(args, "hatch_env", None) + cmd = getattr(args, "cmd", None) + + if env_manager.launch_python_shell(hatch_env, cmd): + return EXIT_SUCCESS + else: + env_name = hatch_env or env_manager.get_current_environment() + reporter = ResultReporter("hatch env python shell") + reporter.report_error(f"Failed to launch Python shell for '{env_name}'") + return EXIT_ERROR + + +def handle_env_python_add_hatch_mcp(args: Namespace) -> int: + """Handle 'hatch env python add-hatch-mcp' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - hatch_env: Optional environment name (default: current) + - tag: Git tag/branch for wrapper installation + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + hatch_env = getattr(args, "hatch_env", None) + tag = getattr(args, "tag", None) + dry_run = getattr(args, "dry_run", False) + + env_name = hatch_env or env_manager.get_current_environment() + + # Create reporter for unified output + reporter = ResultReporter("hatch env python add-hatch-mcp", dry_run=dry_run) + reporter.add(ConsequenceType.INSTALL, f"hatch_mcp_server wrapper in '{env_name}'") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + if env_manager.install_mcp_server(env_name, tag): + reporter.report_result() + return EXIT_SUCCESS + else: + reporter.report_error( + f"Failed to install hatch_mcp_server wrapper in environment '{env_name}'" + ) + return EXIT_ERROR + + +def handle_env_show(args: Namespace) -> int: + """Handle 'hatch env show' command. + + Displays detailed hierarchical view of a specific environment. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - name: Environment name to show + + Returns: + Exit code (0 for success, 1 for error) + + Reference: R02 Β§2.2 (02-list_output_format_specification_v2.md) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + name = args.name + + # Validate environment exists + if not env_manager.environment_exists(name): + format_validation_error( + ValidationError( + f"Environment '{name}' does not exist", + field="name", + suggestion="Use 'hatch env list' to see available environments", + ) + ) + return EXIT_ERROR + + # Get environment data + env_data = env_manager.get_environment_data(name) + current_env = env_manager.get_current_environment() + is_current = name == current_env + + # Header + status = " (active)" if is_current else "" + print(f"Environment: {name}{status}") + + # Description + description = env_data.get("description", "") + if description: + print(f" Description: {description}") + + # Created timestamp + created_at = env_data.get("created_at", "Unknown") + print(f" Created: {created_at}") + print() + + # Python Environment section + python_info = env_manager.get_python_environment_info(name) + print(" Python Environment:") + if python_info: + print(f" Version: {python_info.get('python_version', 'Unknown')}") + print(f" Executable: {python_info.get('python_executable', 'N/A')}") + conda_env = python_info.get("conda_env_name", "N/A") + if conda_env and conda_env != "N/A": + print(f" Conda env: {conda_env}") + status = "Active" if python_info.get("enabled", False) else "Inactive" + print(f" Status: {status}") + else: + print(" (not initialized)") + print() + + # Packages section + packages = env_manager.list_packages(name) + pkg_count = len(packages) if packages else 0 + print(f" Packages ({pkg_count}):") + + if packages: + for pkg in packages: + pkg_name = pkg.get("name", "unknown") + print(f" {pkg_name}") + + # Version + version = pkg.get("version", "unknown") + print(f" Version: {version}") + + # Source + source = pkg.get("source", {}) + source_type = source.get("type", "unknown") + source_path = source.get("path", source.get("url", "N/A")) + print(f" Source: {source_type} ({source_path})") + + # Deployed hosts + configured_hosts = pkg.get("configured_hosts", {}) + if configured_hosts: + hosts_list = ", ".join(configured_hosts.keys()) + print(f" Deployed to: {hosts_list}") + else: + print(" Deployed to: (none)") + print() + else: + print(" (empty)") + + return EXIT_SUCCESS + + +def handle_env_list_hosts(args: Namespace) -> int: + """Handle 'hatch env list hosts' command. + + Lists environment/host/server deployments from environment data. + Shows only Hatch-managed packages and their host deployments. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - env: Optional regex pattern to filter by environment name + - server: Optional regex pattern to filter by server name + - json: Optional flag for JSON output + + Returns: + Exit code (0 for success, 1 for error) + + Reference: R10 Β§3.3 (10-namespace_consistency_specification_v2.md) + """ + import json as json_module + import re + + env_manager: "HatchEnvironmentManager" = args.env_manager + env_pattern: str = getattr(args, "env", None) + server_pattern: str = getattr(args, "server", None) + json_output: bool = getattr(args, "json", False) + + # Compile regex patterns if provided + env_re = None + if env_pattern: + try: + env_re = re.compile(env_pattern) + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid env regex pattern: {e}", + field="--env", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + server_re = None + if server_pattern: + try: + server_re = re.compile(server_pattern) + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid server regex pattern: {e}", + field="--server", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + # Get all environments + environments = env_manager.list_environments() + + # Collect rows: (environment, host, server, version) + rows = [] + + for env_info in environments: + env_name = ( + env_info.get("name", env_info) if isinstance(env_info, dict) else env_info + ) + + # Apply environment filter + if env_re and not env_re.search(env_name): + continue + + try: + env_data = env_manager.get_environment_data(env_name) + packages = ( + env_data.get("packages", []) if isinstance(env_data, dict) else [] + ) + + for pkg in packages: + pkg_name = pkg.get("name") if isinstance(pkg, dict) else None + pkg_version = pkg.get("version", "-") if isinstance(pkg, dict) else "-" + configured_hosts = ( + pkg.get("configured_hosts", {}) if isinstance(pkg, dict) else {} + ) + + if not pkg_name or not configured_hosts: + continue + + # Apply server filter + if server_re and not server_re.search(pkg_name): + continue + + # Add a row for each host deployment + for host_name in configured_hosts.keys(): + rows.append((env_name, host_name, pkg_name, pkg_version)) + except Exception: + continue + + # Sort rows by environment (alphabetically), then host, then server + rows.sort(key=lambda x: (x[0], x[1], x[2])) + + # JSON output per R10 Β§8 + if json_output: + rows_data = [] + for env, host, server, version in rows: + rows_data.append( + {"environment": env, "host": host, "server": server, "version": version} + ) + print(json_module.dumps({"rows": rows_data}, indent=2)) + return EXIT_SUCCESS + + # Display results + if not rows: + if env_pattern or server_pattern: + print("No matching environment host deployments found") + else: + print("No environment host deployments found") + return EXIT_SUCCESS + + print("Environment Host Deployments:") + + # Define table columns per R10 Β§3.3: Environment β†’ Host β†’ Server β†’ Version + columns = [ + ColumnDef(name="Environment", width=15), + ColumnDef(name="Host", width=18), + ColumnDef(name="Server", width=18), + ColumnDef(name="Version", width=10), + ] + formatter = TableFormatter(columns) + + for env, host, server, version in rows: + formatter.add_row([env, host, server, version]) + + print(formatter.render()) + return EXIT_SUCCESS + + +def handle_env_list_servers(args: Namespace) -> int: + """Handle 'hatch env list servers' command. + + Lists environment/server/host deployments from environment data. + Shows only Hatch-managed packages. Undeployed packages show '-' in Host column. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - env: Optional regex pattern to filter by environment name + - host: Optional regex pattern to filter by host name (use '-' for undeployed) + - json: Optional flag for JSON output + + Returns: + Exit code (0 for success, 1 for error) + + Reference: R10 Β§3.4 (10-namespace_consistency_specification_v2.md) + """ + import json as json_module + import re + + env_manager: "HatchEnvironmentManager" = args.env_manager + env_pattern: str = getattr(args, "env", None) + host_pattern: str = getattr(args, "host", None) + json_output: bool = getattr(args, "json", False) + + # Compile regex patterns if provided + env_re = None + if env_pattern: + try: + env_re = re.compile(env_pattern) + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid env regex pattern: {e}", + field="--env", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + # Special handling for '-' (undeployed filter) + filter_undeployed = host_pattern == "-" + host_re = None + if host_pattern and not filter_undeployed: + try: + host_re = re.compile(host_pattern) + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid host regex pattern: {e}", + field="--host", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + # Get all environments + environments = env_manager.list_environments() + + # Collect rows: (environment, server, host, version) + rows = [] + + for env_info in environments: + env_name = ( + env_info.get("name", env_info) if isinstance(env_info, dict) else env_info + ) + + # Apply environment filter + if env_re and not env_re.search(env_name): + continue + + try: + env_data = env_manager.get_environment_data(env_name) + packages = ( + env_data.get("packages", []) if isinstance(env_data, dict) else [] + ) + + for pkg in packages: + pkg_name = pkg.get("name") if isinstance(pkg, dict) else None + pkg_version = pkg.get("version", "-") if isinstance(pkg, dict) else "-" + configured_hosts = ( + pkg.get("configured_hosts", {}) if isinstance(pkg, dict) else {} + ) + + if not pkg_name: + continue + + if configured_hosts: + # Package is deployed to one or more hosts + for host_name in configured_hosts.keys(): + # Apply host filter + if filter_undeployed: + # Skip deployed packages when filtering for undeployed + continue + if host_re and not host_re.search(host_name): + continue + rows.append((env_name, pkg_name, host_name, pkg_version)) + else: + # Package is not deployed (undeployed) + if host_re: + # Skip undeployed when filtering by specific host pattern + continue + if not filter_undeployed and host_pattern: + # Skip undeployed when filtering by host (unless specifically filtering for undeployed) + continue + rows.append((env_name, pkg_name, "-", pkg_version)) + except Exception: + continue + + # Sort rows by environment (alphabetically), then server, then host + rows.sort(key=lambda x: (x[0], x[1], x[2])) + + # JSON output per R10 Β§8 + if json_output: + rows_data = [] + for env, server, host, version in rows: + rows_data.append( + { + "environment": env, + "server": server, + "host": host if host != "-" else None, + "version": version, + } + ) + print(json_module.dumps({"rows": rows_data}, indent=2)) + return EXIT_SUCCESS + + # Display results + if not rows: + if env_pattern or host_pattern: + print("No matching environment server deployments found") + else: + print("No environment server deployments found") + return EXIT_SUCCESS + + print("Environment Servers:") + + # Define table columns per R10 Β§3.4: Environment β†’ Server β†’ Host β†’ Version + columns = [ + ColumnDef(name="Environment", width=15), + ColumnDef(name="Server", width=18), + ColumnDef(name="Host", width=18), + ColumnDef(name="Version", width=10), + ] + formatter = TableFormatter(columns) + + for env, server, host, version in rows: + formatter.add_row([env, server, host, version]) + + print(formatter.render()) + return EXIT_SUCCESS diff --git a/hatch/cli/cli_mcp.py b/hatch/cli/cli_mcp.py new file mode 100644 index 0000000..457e2f4 --- /dev/null +++ b/hatch/cli/cli_mcp.py @@ -0,0 +1,2297 @@ +"""MCP host configuration handlers for Hatch CLI. + +This module provides handlers for MCP (Model Context Protocol) host configuration +commands. MCP enables AI assistants to interact with external tools and services +through a standardized protocol. + +Supported Hosts: + - claude-desktop: Claude Desktop application + - claude-code: Claude Code extension + - cursor: Cursor IDE + - vscode: Visual Studio Code with Copilot + - kiro: Kiro IDE + - codex: OpenAI Codex + - lm-studio: LM Studio + - gemini: Google Gemini + +Command Groups: + Discovery: + - hatch mcp discover hosts: Detect available MCP host platforms + - hatch mcp discover servers: Find MCP servers in packages + + Listing: + - hatch mcp list hosts: Show configured hosts in environment + - hatch mcp list servers: Show configured servers + + Backup: + - hatch mcp backup restore: Restore configuration from backup + - hatch mcp backup list: List available backups + - hatch mcp backup clean: Clean old backups + + Configuration: + - hatch mcp configure: Add or update MCP server configuration + - hatch mcp remove: Remove server from specific host + - hatch mcp remove-server: Remove server from multiple hosts + - hatch mcp remove-host: Remove all servers from a host + + Synchronization: + - hatch mcp sync: Sync package servers to hosts + +Handler Signature: + All handlers follow: (args: Namespace) -> int + Returns EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure. + +Example: + $ hatch mcp discover hosts + $ hatch mcp configure claude-desktop my-server --command python --args server.py + $ hatch mcp backup list claude-desktop --detailed +""" + +from argparse import Namespace +from typing import Optional + +from hatch.environment_manager import HatchEnvironmentManager +from hatch.mcp_host_config import ( + MCPHostConfigurationManager, + MCPHostRegistry, + MCPHostType, + MCPServerConfig, +) + +from hatch.cli.cli_utils import ( + EXIT_SUCCESS, + EXIT_ERROR, + get_package_mcp_server_config, + TableFormatter, + ColumnDef, + ValidationError, + format_validation_error, + format_info, + ResultReporter, +) + + +def handle_mcp_discover_hosts(args: Namespace) -> int: + """Handle 'hatch mcp discover hosts' command. + + Detects and displays available MCP host platforms on the system. + + Args: + args: Parsed command-line arguments containing: + - json: Optional flag for JSON output + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + try: + import json as json_module + + # Import strategies to trigger registration + + json_output: bool = getattr(args, "json", False) + available_hosts = MCPHostRegistry.detect_available_hosts() + + if json_output: + # JSON output + hosts_data = [] + for host_type in MCPHostType: + try: + strategy = MCPHostRegistry.get_strategy(host_type) + config_path = strategy.get_config_path() + is_available = host_type in available_hosts + + hosts_data.append( + { + "host": host_type.value, + "available": is_available, + "config_path": str(config_path) if config_path else None, + } + ) + except Exception as e: + hosts_data.append( + {"host": host_type.value, "available": False, "error": str(e)} + ) + + print(json_module.dumps({"hosts": hosts_data}, indent=2)) + return EXIT_SUCCESS + + # Table output + print("Available MCP Host Platforms:") + + # Define table columns per R02 Β§2.3 + columns = [ + ColumnDef(name="Host", width=18), + ColumnDef(name="Status", width=15), + ColumnDef(name="Config Path", width="auto"), + ] + formatter = TableFormatter(columns) + + for host_type in MCPHostType: + try: + strategy = MCPHostRegistry.get_strategy(host_type) + config_path = strategy.get_config_path() + is_available = host_type in available_hosts + + status = "βœ“ Available" if is_available else "βœ— Not Found" + path_str = str(config_path) if config_path else "-" + formatter.add_row([host_type.value, status, path_str]) + except Exception as e: + formatter.add_row([host_type.value, "Error", str(e)[:30]]) + + print(formatter.render()) + return EXIT_SUCCESS + except Exception as e: + reporter = ResultReporter("hatch mcp discover hosts") + reporter.report_error("Failed to discover hosts", details=[f"Reason: {str(e)}"]) + return EXIT_ERROR + + +def handle_mcp_discover_servers(args: Namespace) -> int: + """Handle 'hatch mcp discover servers' command. + + .. deprecated:: + This command is deprecated. Use 'hatch mcp list servers' instead. + + Discovers MCP servers available in packages within an environment. + + Args: + args: Parsed command-line arguments containing: + - env_manager: HatchEnvironmentManager instance + - env: Optional environment name (uses current if not specified) + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + import sys + + # Emit deprecation warning to stderr + print( + "Warning: 'hatch mcp discover servers' is deprecated. " + "Use 'hatch mcp list servers' instead.", + file=sys.stderr, + ) + + try: + env_manager: HatchEnvironmentManager = args.env_manager + env_name: Optional[str] = getattr(args, "env", None) + + env_name = env_name or env_manager.get_current_environment() + + if not env_manager.environment_exists(env_name): + format_validation_error( + ValidationError( + f"Environment '{env_name}' does not exist", + field="--env", + suggestion="Use 'hatch env list' to see available environments", + ) + ) + return EXIT_ERROR + + packages = env_manager.list_packages(env_name) + mcp_packages = [] + + for package in packages: + try: + # Check if package has MCP server entry point + server_config = get_package_mcp_server_config( + env_manager, env_name, package["name"] + ) + mcp_packages.append( + {"package": package, "server_config": server_config} + ) + except ValueError: + # Package doesn't have MCP server + continue + + if not mcp_packages: + print(f"No MCP servers found in environment '{env_name}'") + return EXIT_SUCCESS + + print(f"MCP servers in environment '{env_name}':") + for item in mcp_packages: + package = item["package"] + server_config = item["server_config"] + print(f" {server_config.name}:") + print( + f" Package: {package['name']} v{package.get('version', 'unknown')}" + ) + print(f" Command: {server_config.command}") + print(f" Args: {server_config.args}") + if server_config.env: + print(f" Environment: {server_config.env}") + + return EXIT_SUCCESS + except Exception as e: + reporter = ResultReporter("hatch mcp discover servers") + reporter.report_error( + "Failed to discover servers", details=[f"Reason: {str(e)}"] + ) + return EXIT_ERROR + + +def handle_mcp_list_hosts(args: Namespace) -> int: + """Handle 'hatch mcp list hosts' command - host-centric design. + + Lists host/server pairs from host configuration files. Shows ALL servers + on hosts (both Hatch-managed and 3rd party) with Hatch management status. + + Args: + args: Parsed command-line arguments containing: + - env_manager: HatchEnvironmentManager instance + - server: Optional regex pattern to filter by server name + - json: Optional flag for JSON output + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + + Reference: R10 Β§3.1 (10-namespace_consistency_specification_v2.md) + """ + try: + import json as json_module + import re + + # Import strategies to trigger registration + + env_manager: HatchEnvironmentManager = args.env_manager + server_pattern: Optional[str] = getattr(args, "server", None) + json_output: bool = getattr(args, "json", False) + + # Compile regex pattern if provided + pattern_re = None + if server_pattern: + try: + pattern_re = re.compile(server_pattern) + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid regex pattern '{server_pattern}': {e}", + field="--server", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + # Build Hatch management lookup: {server_name: {host: env_name}} + hatch_managed = {} + for env_info in env_manager.list_environments(): + env_name = ( + env_info.get("name", env_info) + if isinstance(env_info, dict) + else env_info + ) + try: + env_data = env_manager.get_environment_data(env_name) + packages = ( + env_data.get("packages", []) + if isinstance(env_data, dict) + else getattr(env_data, "packages", []) + ) + + for pkg in packages: + pkg_name = ( + pkg.get("name") + if isinstance(pkg, dict) + else getattr(pkg, "name", None) + ) + configured_hosts = ( + pkg.get("configured_hosts", {}) + if isinstance(pkg, dict) + else getattr(pkg, "configured_hosts", {}) + ) + + if pkg_name: + if pkg_name not in hatch_managed: + hatch_managed[pkg_name] = {} + for host_name in configured_hosts.keys(): + hatch_managed[pkg_name][host_name] = env_name + except Exception: + continue + + # Get all available hosts and read their configurations + available_hosts = MCPHostRegistry.detect_available_hosts() + + # Collect host/server pairs from host config files + # Format: (host, server, is_hatch_managed, env_name) + host_rows = [] + + for host_type in available_hosts: + try: + strategy = MCPHostRegistry.get_strategy(host_type) + host_config = strategy.read_configuration() + host_name = host_type.value + + for server_name, server_config in host_config.servers.items(): + # Apply server pattern filter if specified + if pattern_re and not pattern_re.search(server_name): + continue + + # Check if Hatch-managed + is_hatch_managed = False + env_name = None + + if server_name in hatch_managed: + host_info = hatch_managed[server_name].get(host_name) + if host_info: + is_hatch_managed = True + env_name = host_info + + host_rows.append( + (host_name, server_name, is_hatch_managed, env_name) + ) + except Exception: + # Skip hosts that can't be read + continue + + # Sort rows by host (alphabetically), then by server + host_rows.sort(key=lambda x: (x[0], x[1])) + + # JSON output per R10 Β§8 + if json_output: + rows_data = [] + for host, server, is_hatch, env in host_rows: + rows_data.append( + { + "host": host, + "server": server, + "hatch_managed": is_hatch, + "environment": env, + } + ) + print(json_module.dumps({"rows": rows_data}, indent=2)) + return EXIT_SUCCESS + + # Display results + if not host_rows: + if server_pattern: + print(f"No MCP servers matching '{server_pattern}' on any host") + else: + print("No MCP servers found on any available hosts") + return EXIT_SUCCESS + + print("MCP Hosts:") + + # Define table columns per R10 Β§3.1: Host β†’ Server β†’ Hatch β†’ Environment + columns = [ + ColumnDef(name="Host", width=18), + ColumnDef(name="Server", width=18), + ColumnDef(name="Hatch", width=8), + ColumnDef(name="Environment", width=15), + ] + formatter = TableFormatter(columns) + + for host, server, is_hatch, env in host_rows: + hatch_status = "βœ…" if is_hatch else "❌" + env_display = env if env else "-" + formatter.add_row([host, server, hatch_status, env_display]) + + print(formatter.render()) + return EXIT_SUCCESS + except Exception as e: + reporter = ResultReporter("hatch mcp list hosts") + reporter.report_error("Failed to list hosts", details=[f"Reason: {str(e)}"]) + return EXIT_ERROR + + +def handle_mcp_list_servers(args: Namespace) -> int: + """Handle 'hatch mcp list servers' command. + + Lists server/host pairs from host configuration files. Shows ALL servers + on hosts (both Hatch-managed and 3rd party) with Hatch management status. + + Args: + args: Parsed command-line arguments containing: + - env_manager: HatchEnvironmentManager instance + - host: Optional regex pattern to filter by host name + - json: Optional flag for JSON output + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + + Reference: R10 Β§3.2 (10-namespace_consistency_specification_v2.md) + """ + try: + import json as json_module + import re + + # Import strategies to trigger registration + + env_manager: HatchEnvironmentManager = args.env_manager + host_pattern: Optional[str] = getattr(args, "host", None) + json_output: bool = getattr(args, "json", False) + + # Compile host regex pattern if provided + host_re = None + if host_pattern: + try: + host_re = re.compile(host_pattern) + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid regex pattern '{host_pattern}': {e}", + field="--host", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + # Get all available hosts + available_hosts = MCPHostRegistry.detect_available_hosts() + + # Build Hatch management lookup: {server_name: {host: (env_name, version)}} + hatch_managed = {} + for env_info in env_manager.list_environments(): + env_name = ( + env_info.get("name", env_info) + if isinstance(env_info, dict) + else env_info + ) + try: + env_data = env_manager.get_environment_data(env_name) + packages = ( + env_data.get("packages", []) + if isinstance(env_data, dict) + else getattr(env_data, "packages", []) + ) + + for pkg in packages: + pkg_name = ( + pkg.get("name") + if isinstance(pkg, dict) + else getattr(pkg, "name", None) + ) + pkg_version = ( + pkg.get("version", "-") + if isinstance(pkg, dict) + else getattr(pkg, "version", "-") + ) + configured_hosts = ( + pkg.get("configured_hosts", {}) + if isinstance(pkg, dict) + else getattr(pkg, "configured_hosts", {}) + ) + + if pkg_name: + if pkg_name not in hatch_managed: + hatch_managed[pkg_name] = {} + for host_name in configured_hosts.keys(): + hatch_managed[pkg_name][host_name] = (env_name, pkg_version) + except Exception: + continue + + # Collect server data from host config files + # Format: (server_name, host, is_hatch_managed, env_name, version) + server_rows = [] + + for host_type in available_hosts: + try: + strategy = MCPHostRegistry.get_strategy(host_type) + host_config = strategy.read_configuration() + host_name = host_type.value + + # Apply host pattern filter if specified + if host_re and not host_re.search(host_name): + continue + + for server_name, server_config in host_config.servers.items(): + # Check if Hatch-managed + is_hatch_managed = False + env_name = "-" + version = "-" + + if server_name in hatch_managed: + host_info = hatch_managed[server_name].get(host_name) + if host_info: + is_hatch_managed = True + env_name, version = host_info + + server_rows.append( + (server_name, host_name, is_hatch_managed, env_name, version) + ) + except Exception: + # Skip hosts that can't be read + continue + + # Sort rows by server (alphabetically), then by host per R10 Β§3.2 + server_rows.sort(key=lambda x: (x[0], x[1])) + + # JSON output + if json_output: + servers_data = [] + for server_name, host, is_hatch, env, version in server_rows: + server_entry = { + "server": server_name, + "host": host, + "hatch_managed": is_hatch, + "environment": env if is_hatch else None, + } + servers_data.append(server_entry) + + print(json_module.dumps({"rows": servers_data}, indent=2)) + return EXIT_SUCCESS + + if not server_rows: + if host_pattern: + print(f"No MCP servers on hosts matching '{host_pattern}'") + else: + print("No MCP servers found on any available hosts") + return EXIT_SUCCESS + + print("MCP Servers:") + + # Define table columns per R10 Β§3.2: Server β†’ Host β†’ Hatch β†’ Environment + columns = [ + ColumnDef(name="Server", width=18), + ColumnDef(name="Host", width=18), + ColumnDef(name="Hatch", width=8), + ColumnDef(name="Environment", width=15), + ] + formatter = TableFormatter(columns) + + for server_name, host, is_hatch, env, version in server_rows: + hatch_status = "βœ…" if is_hatch else "❌" + env_display = env if is_hatch else "-" + formatter.add_row([server_name, host, hatch_status, env_display]) + + print(formatter.render()) + return EXIT_SUCCESS + except Exception as e: + reporter = ResultReporter("hatch mcp list servers") + reporter.report_error("Failed to list servers", details=[f"Reason: {str(e)}"]) + return EXIT_ERROR + + +def handle_mcp_show_hosts(args: Namespace) -> int: + """Handle 'hatch mcp show hosts' command. + + Shows detailed hierarchical view of all MCP host configurations. + Supports --server filter for regex pattern matching. + + Args: + args: Parsed command-line arguments containing: + - env_manager: HatchEnvironmentManager instance + - server: Optional regex pattern to filter by server name + - json: Optional flag for JSON output + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + + Reference: R11 Β§2.1 (11-enhancing_show_command_v0.md) + """ + try: + import json as json_module + import re + import os + import datetime + + # Import strategies to trigger registration + from hatch.mcp_host_config.backup import MCPHostConfigBackupManager + from hatch.cli.cli_utils import highlight + + env_manager: HatchEnvironmentManager = args.env_manager + server_pattern: Optional[str] = getattr(args, "server", None) + json_output: bool = getattr(args, "json", False) + + # Compile regex pattern if provided + pattern_re = None + if server_pattern: + try: + pattern_re = re.compile(server_pattern) + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid regex pattern '{server_pattern}': {e}", + field="--server", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + # Build Hatch management lookup: {server_name: {host: (env_name, version, last_synced)}} + hatch_managed = {} + for env_info in env_manager.list_environments(): + env_name = ( + env_info.get("name", env_info) + if isinstance(env_info, dict) + else env_info + ) + try: + env_data = env_manager.get_environment_data(env_name) + packages = ( + env_data.get("packages", []) + if isinstance(env_data, dict) + else getattr(env_data, "packages", []) + ) + + for pkg in packages: + pkg_name = ( + pkg.get("name") + if isinstance(pkg, dict) + else getattr(pkg, "name", None) + ) + pkg_version = ( + pkg.get("version", "unknown") + if isinstance(pkg, dict) + else getattr(pkg, "version", "unknown") + ) + configured_hosts = ( + pkg.get("configured_hosts", {}) + if isinstance(pkg, dict) + else getattr(pkg, "configured_hosts", {}) + ) + + if pkg_name: + if pkg_name not in hatch_managed: + hatch_managed[pkg_name] = {} + for host_name, host_info in configured_hosts.items(): + last_synced = ( + host_info.get("configured_at", "N/A") + if isinstance(host_info, dict) + else "N/A" + ) + hatch_managed[pkg_name][host_name] = ( + env_name, + pkg_version, + last_synced, + ) + except Exception: + continue + + # Get all available hosts + available_hosts = MCPHostRegistry.detect_available_hosts() + + # Sort hosts alphabetically + sorted_hosts = sorted(available_hosts, key=lambda h: h.value) + + # Collect host data for output + hosts_data = [] + + for host_type in sorted_hosts: + try: + strategy = MCPHostRegistry.get_strategy(host_type) + host_config = strategy.read_configuration() + host_name = host_type.value + config_path = strategy.get_config_path() + + # Filter servers by pattern if specified + filtered_servers = {} + for server_name, server_config in host_config.servers.items(): + if pattern_re and not pattern_re.search(server_name): + continue + filtered_servers[server_name] = server_config + + # Skip host if no matching servers + if not filtered_servers: + continue + + # Get host metadata + last_modified = None + if config_path and config_path.exists(): + mtime = os.path.getmtime(config_path) + last_modified = datetime.datetime.fromtimestamp(mtime).strftime( + "%Y-%m-%d %H:%M:%S" + ) + + backup_manager = MCPHostConfigBackupManager() + backups = backup_manager.list_backups(host_name) + backup_count = len(backups) if backups else 0 + + # Build server data + servers_data = [] + for server_name in sorted(filtered_servers.keys()): + server_config = filtered_servers[server_name] + + # Check if Hatch-managed + hatch_info = hatch_managed.get(server_name, {}).get(host_name) + is_hatch_managed = hatch_info is not None + env_name = hatch_info[0] if hatch_info else None + pkg_version = hatch_info[1] if hatch_info else None + last_synced = hatch_info[2] if hatch_info else None + + server_data = { + "name": server_name, + "hatch_managed": is_hatch_managed, + "environment": env_name, + "version": pkg_version, + "command": getattr(server_config, "command", None), + "args": getattr(server_config, "args", None), + "url": getattr(server_config, "url", None), + "env": {}, + "last_synced": last_synced, + } + + # Get environment variables (hide sensitive values for display) + env_vars = getattr(server_config, "env", None) + if env_vars: + for key, value in env_vars.items(): + if any( + sensitive in key.upper() + for sensitive in [ + "KEY", + "SECRET", + "TOKEN", + "PASSWORD", + "CREDENTIAL", + ] + ): + server_data["env"][key] = "****** (hidden)" + else: + server_data["env"][key] = value + + servers_data.append(server_data) + + hosts_data.append( + { + "host": host_name, + "config_path": str(config_path) if config_path else None, + "last_modified": last_modified, + "backup_count": backup_count, + "servers": servers_data, + } + ) + except Exception: + continue + + # JSON output + if json_output: + print(json_module.dumps({"hosts": hosts_data}, indent=2)) + return EXIT_SUCCESS + + # Human-readable output + if not hosts_data: + if server_pattern: + print(f"No hosts with servers matching '{server_pattern}'") + else: + print("No MCP hosts found") + return EXIT_SUCCESS + + separator = "═" * 79 + + for host_data in hosts_data: + # Horizontal separator + print(separator) + + # Host header with highlight + print(f"MCP Host: {highlight(host_data['host'])}") + print(f" Config Path: {host_data['config_path'] or 'N/A'}") + print(f" Last Modified: {host_data['last_modified'] or 'N/A'}") + if host_data["backup_count"] > 0: + print(f" Backup Available: Yes ({host_data['backup_count']} backups)") + else: + print(" Backup Available: No") + print() + + # Configured Servers section + print(f" Configured Servers ({len(host_data['servers'])}):") + + for server in host_data["servers"]: + # Server header with highlight + if server["hatch_managed"]: + print( + f" {highlight(server['name'])} (Hatch-managed: {server['environment']})" + ) + else: + print(f" {highlight(server['name'])} (Not Hatch-managed)") + + # Command and args + if server["command"]: + print(f" Command: {server['command']}") + if server["args"]: + print(f" Args: {server['args']}") + + # URL for remote servers + if server["url"]: + print(f" URL: {server['url']}") + + # Environment variables + if server["env"]: + print(" Environment Variables:") + for key, value in server["env"].items(): + print(f" {key}: {value}") + + # Hatch-specific info + if server["hatch_managed"]: + if server["last_synced"]: + print(f" Last Synced: {server['last_synced']}") + if server["version"]: + print(f" Package Version: {server['version']}") + + print() + + return EXIT_SUCCESS + except Exception as e: + reporter = ResultReporter("hatch mcp show hosts") + reporter.report_error( + "Failed to show host configurations", details=[f"Reason: {str(e)}"] + ) + return EXIT_ERROR + + +def handle_mcp_show_servers(args: Namespace) -> int: + """Handle 'hatch mcp show servers' command. + + Shows detailed hierarchical view of all MCP server configurations across hosts. + Supports --host filter for regex pattern matching. + + Args: + args: Parsed command-line arguments containing: + - env_manager: HatchEnvironmentManager instance + - host: Optional regex pattern to filter by host name + - json: Optional flag for JSON output + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + + Reference: R11 Β§2.2 (11-enhancing_show_command_v0.md) + """ + try: + import json as json_module + import re + + # Import strategies to trigger registration + from hatch.cli.cli_utils import highlight + + env_manager: HatchEnvironmentManager = args.env_manager + host_pattern: Optional[str] = getattr(args, "host", None) + json_output: bool = getattr(args, "json", False) + + # Compile regex pattern if provided + pattern_re = None + if host_pattern: + try: + pattern_re = re.compile(host_pattern) + except re.error as e: + format_validation_error( + ValidationError( + f"Invalid regex pattern '{host_pattern}': {e}", + field="--host", + suggestion="Use a valid Python regex pattern", + ) + ) + return EXIT_ERROR + + # Build Hatch management lookup: {server_name: {host: (env_name, version, last_synced)}} + hatch_managed = {} + for env_info in env_manager.list_environments(): + env_name = ( + env_info.get("name", env_info) + if isinstance(env_info, dict) + else env_info + ) + try: + env_data = env_manager.get_environment_data(env_name) + packages = ( + env_data.get("packages", []) + if isinstance(env_data, dict) + else getattr(env_data, "packages", []) + ) + + for pkg in packages: + pkg_name = ( + pkg.get("name") + if isinstance(pkg, dict) + else getattr(pkg, "name", None) + ) + pkg_version = ( + pkg.get("version", "unknown") + if isinstance(pkg, dict) + else getattr(pkg, "version", "unknown") + ) + configured_hosts = ( + pkg.get("configured_hosts", {}) + if isinstance(pkg, dict) + else getattr(pkg, "configured_hosts", {}) + ) + + if pkg_name: + if pkg_name not in hatch_managed: + hatch_managed[pkg_name] = {} + for host_name, host_info in configured_hosts.items(): + last_synced = ( + host_info.get("configured_at", "N/A") + if isinstance(host_info, dict) + else "N/A" + ) + hatch_managed[pkg_name][host_name] = ( + env_name, + pkg_version, + last_synced, + ) + except Exception: + continue + + # Get all available hosts + available_hosts = MCPHostRegistry.detect_available_hosts() + + # Build server β†’ hosts mapping + # Format: {server_name: [(host_name, server_config, hatch_info), ...]} + server_hosts_map = {} + + for host_type in available_hosts: + host_name = host_type.value + + # Apply host pattern filter if specified + if pattern_re and not pattern_re.search(host_name): + continue + + try: + strategy = MCPHostRegistry.get_strategy(host_type) + host_config = strategy.read_configuration() + + for server_name, server_config in host_config.servers.items(): + if server_name not in server_hosts_map: + server_hosts_map[server_name] = [] + + # Get Hatch management info for this server on this host + hatch_info = hatch_managed.get(server_name, {}).get(host_name) + + server_hosts_map[server_name].append( + (host_name, server_config, hatch_info) + ) + except Exception: + continue + + # Sort servers alphabetically + sorted_servers = sorted(server_hosts_map.keys()) + + # Collect server data for output + servers_data = [] + + for server_name in sorted_servers: + host_entries = server_hosts_map[server_name] + + # Skip server if no matching hosts (after filter) + if not host_entries: + continue + + # Determine overall Hatch management status + # A server is Hatch-managed if it's managed on ANY host + any_hatch_managed = any(h[2] is not None for h in host_entries) + + # Get version from first Hatch-managed entry (if any) + pkg_version = None + pkg_env = None + for _, _, hatch_info in host_entries: + if hatch_info: + pkg_env = hatch_info[0] + pkg_version = hatch_info[1] + break + + # Build host configurations data + hosts_data = [] + for host_name, server_config, hatch_info in sorted( + host_entries, key=lambda x: x[0] + ): + host_data = { + "host": host_name, + "command": getattr(server_config, "command", None), + "args": getattr(server_config, "args", None), + "url": getattr(server_config, "url", None), + "env": {}, + "last_synced": hatch_info[2] if hatch_info else None, + } + + # Get environment variables (hide sensitive values) + env_vars = getattr(server_config, "env", None) + if env_vars: + for key, value in env_vars.items(): + if any( + sensitive in key.upper() + for sensitive in [ + "KEY", + "SECRET", + "TOKEN", + "PASSWORD", + "CREDENTIAL", + ] + ): + host_data["env"][key] = "****** (hidden)" + else: + host_data["env"][key] = value + + hosts_data.append(host_data) + + servers_data.append( + { + "name": server_name, + "hatch_managed": any_hatch_managed, + "environment": pkg_env, + "version": pkg_version, + "hosts": hosts_data, + } + ) + + # JSON output + if json_output: + print(json_module.dumps({"servers": servers_data}, indent=2)) + return EXIT_SUCCESS + + # Human-readable output + if not servers_data: + if host_pattern: + print(f"No servers on hosts matching '{host_pattern}'") + else: + print("No MCP servers found") + return EXIT_SUCCESS + + separator = "═" * 79 + + for server_data in servers_data: + # Horizontal separator + print(separator) + + # Server header with highlight + print(f"MCP Server: {highlight(server_data['name'])}") + if server_data["hatch_managed"]: + print(f" Hatch Managed: Yes ({server_data['environment']})") + if server_data["version"]: + print(f" Package Version: {server_data['version']}") + else: + print(" Hatch Managed: No") + print() + + # Host Configurations section + print(f" Host Configurations ({len(server_data['hosts'])}):") + + for host in server_data["hosts"]: + # Host header with highlight + print(f" {highlight(host['host'])}:") + + # Command and args + if host["command"]: + print(f" Command: {host['command']}") + if host["args"]: + print(f" Args: {host['args']}") + + # URL for remote servers + if host["url"]: + print(f" URL: {host['url']}") + + # Environment variables + if host["env"]: + print(" Environment Variables:") + for key, value in host["env"].items(): + print(f" {key}: {value}") + + # Last synced (if Hatch-managed) + if host["last_synced"]: + print(f" Last Synced: {host['last_synced']}") + + print() + + return EXIT_SUCCESS + except Exception as e: + reporter = ResultReporter("hatch mcp show servers") + reporter.report_error( + "Failed to show server configurations", details=[f"Reason: {str(e)}"] + ) + return EXIT_ERROR + + +def handle_mcp_backup_restore(args: Namespace) -> int: + """Handle 'hatch mcp backup restore' command. + + Args: + args: Parsed command-line arguments containing: + - env_manager: HatchEnvironmentManager instance + - host: Host platform to restore + - backup_file: Optional specific backup file (default: latest) + - dry_run: Preview without execution + - auto_approve: Skip confirmation prompts + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + from hatch.cli.cli_utils import ( + request_confirmation, + ResultReporter, + ConsequenceType, + ) + + try: + from hatch.mcp_host_config.backup import MCPHostConfigBackupManager + + env_manager: HatchEnvironmentManager = args.env_manager + host: str = args.host + backup_file: Optional[str] = getattr(args, "backup_file", None) + dry_run: bool = getattr(args, "dry_run", False) + auto_approve: bool = getattr(args, "auto_approve", False) + + # Validate host type + try: + MCPHostType(host) # Validate host type enum + except ValueError: + format_validation_error( + ValidationError( + f"Invalid host '{host}'", + field="--host", + suggestion=f"Supported hosts: {', '.join(h.value for h in MCPHostType)}", + ) + ) + return EXIT_ERROR + + backup_manager = MCPHostConfigBackupManager() + + # Get backup file path + if backup_file: + backup_path = backup_manager.backup_root / host / backup_file + if not backup_path.exists(): + format_validation_error( + ValidationError( + f"Backup file '{backup_file}' not found for host '{host}'", + field="backup_file", + suggestion=f"Use 'hatch mcp backup list {host}' to see available backups", + ) + ) + return EXIT_ERROR + else: + backup_path = backup_manager._get_latest_backup(host) + if not backup_path: + format_validation_error( + ValidationError( + f"No backups found for host '{host}'", + field="--host", + suggestion="Create a backup first with 'hatch mcp configure' which auto-creates backups", + ) + ) + return EXIT_ERROR + backup_file = backup_path.name + + # Create ResultReporter for unified output + reporter = ResultReporter("hatch mcp backup restore", dry_run=dry_run) + reporter.add( + ConsequenceType.RESTORE, f"Backup '{backup_file}' to host '{host}'" + ) + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt for confirmation + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + # Confirm operation unless auto-approved + if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Perform restoration + success = backup_manager.restore_backup(host, backup_file) + + if success: + reporter.report_result() + + # Read restored configuration to get actual server list + try: + # Import strategies to trigger registration + + host_type = MCPHostType(host) # Validate and get host type enum + strategy = MCPHostRegistry.get_strategy(host_type) + restored_config = strategy.read_configuration() + + # Update environment tracking to match restored state + updates_count = ( + env_manager.apply_restored_host_configuration_to_environments( + host, restored_config.servers + ) + ) + if updates_count > 0: + print( + f" Synchronized {updates_count} package entries with restored configuration" + ) + + except Exception as e: + from hatch.cli.cli_utils import Color, _colors_enabled + + if _colors_enabled(): + print( + f" {Color.YELLOW.value}[WARNING]{Color.RESET.value} Could not synchronize environment tracking: {e}" + ) + else: + print( + f" [WARNING] Could not synchronize environment tracking: {e}" + ) + + return EXIT_SUCCESS + else: + reporter = ResultReporter("hatch mcp backup restore") + reporter.report_error( + f"Failed to restore backup '{backup_file}'", details=[f"Host: {host}"] + ) + return EXIT_ERROR + + except Exception as e: + reporter = ResultReporter("hatch mcp backup restore") + reporter.report_error("Failed to restore backup", details=[f"Reason: {str(e)}"]) + return EXIT_ERROR + + +def handle_mcp_backup_list(args: Namespace) -> int: + """Handle 'hatch mcp backup list' command. + + Args: + args: Parsed command-line arguments containing: + - host: Host platform to list backups for + - detailed: Show detailed backup information + - json: Optional flag for JSON output + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + try: + import json as json_module + from hatch.mcp_host_config.backup import MCPHostConfigBackupManager + + host: str = args.host + detailed: bool = getattr(args, "detailed", False) + json_output: bool = getattr(args, "json", False) + + # Validate host type + try: + MCPHostType(host) # Validate host type enum + except ValueError: + format_validation_error( + ValidationError( + f"Invalid host '{host}'", + field="--host", + suggestion=f"Supported hosts: {', '.join(h.value for h in MCPHostType)}", + ) + ) + return EXIT_ERROR + + backup_manager = MCPHostConfigBackupManager() + backups = backup_manager.list_backups(host) + + # JSON output + if json_output: + backups_data = [] + for backup in backups: + backups_data.append( + { + "file": backup.file_path.name, + "created": backup.timestamp.strftime("%Y-%m-%d %H:%M:%S"), + "size_bytes": backup.file_size, + "age_days": backup.age_days, + } + ) + print(json_module.dumps({"host": host, "backups": backups_data}, indent=2)) + return EXIT_SUCCESS + + if not backups: + print(f"No backups found for host '{host}'") + return EXIT_SUCCESS + + print(f"Backups for host '{host}' ({len(backups)} found):") + + if detailed: + # Define table columns per R02 Β§2.7 + columns = [ + ColumnDef(name="Backup File", width=40), + ColumnDef(name="Created", width=20), + ColumnDef(name="Size", width=12, align="right"), + ColumnDef(name="Age (days)", width=10, align="right"), + ] + formatter = TableFormatter(columns) + + for backup in backups: + created = backup.timestamp.strftime("%Y-%m-%d %H:%M:%S") + size = f"{backup.file_size:,} B" + age = str(backup.age_days) + formatter.add_row([backup.file_path.name, created, size, age]) + + print(formatter.render()) + else: + for backup in backups: + created = backup.timestamp.strftime("%Y-%m-%d %H:%M:%S") + print( + f" {backup.file_path.name} (created: {created}, {backup.age_days} days ago)" + ) + + return EXIT_SUCCESS + except Exception as e: + reporter = ResultReporter("hatch mcp backup list") + reporter.report_error("Failed to list backups", details=[f"Reason: {str(e)}"]) + return EXIT_ERROR + + +def handle_mcp_backup_clean(args: Namespace) -> int: + """Handle 'hatch mcp backup clean' command. + + Args: + args: Parsed command-line arguments containing: + - host: Host platform to clean backups for + - older_than_days: Remove backups older than specified days + - keep_count: Keep only the specified number of newest backups + - dry_run: Preview without execution + - auto_approve: Skip confirmation prompts + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + from hatch.cli.cli_utils import ( + request_confirmation, + ResultReporter, + ConsequenceType, + ) + + try: + from hatch.mcp_host_config.backup import MCPHostConfigBackupManager + + host: str = args.host + older_than_days: Optional[int] = getattr(args, "older_than_days", None) + keep_count: Optional[int] = getattr(args, "keep_count", None) + dry_run: bool = getattr(args, "dry_run", False) + auto_approve: bool = getattr(args, "auto_approve", False) + + # Validate host type + try: + MCPHostType(host) # Validate host type enum + except ValueError: + format_validation_error( + ValidationError( + f"Invalid host '{host}'", + field="--host", + suggestion=f"Supported hosts: {', '.join(h.value for h in MCPHostType)}", + ) + ) + return EXIT_ERROR + + # Validate cleanup criteria + if not older_than_days and not keep_count: + format_validation_error( + ValidationError( + "Must specify either --older-than-days or --keep-count", + suggestion="Use --older-than-days N to remove backups older than N days, or --keep-count N to keep only the N most recent", + ) + ) + return EXIT_ERROR + + backup_manager = MCPHostConfigBackupManager() + backups = backup_manager.list_backups(host) + + if not backups: + print(f"No backups found for host '{host}'") + return EXIT_SUCCESS + + # Determine which backups would be cleaned + to_clean = [] + + if older_than_days: + for backup in backups: + if backup.age_days > older_than_days: + to_clean.append(backup) + + if keep_count and len(backups) > keep_count: + # Keep newest backups, remove oldest + to_clean.extend(backups[keep_count:]) + + # Remove duplicates while preserving order + seen = set() + unique_to_clean = [] + for backup in to_clean: + if backup.file_path not in seen: + seen.add(backup.file_path) + unique_to_clean.append(backup) + + if not unique_to_clean: + print(f"No backups match cleanup criteria for host '{host}'") + return EXIT_SUCCESS + + # Create ResultReporter for unified output + reporter = ResultReporter("hatch mcp backup clean", dry_run=dry_run) + for backup in unique_to_clean: + reporter.add( + ConsequenceType.CLEAN, + f"{backup.file_path.name} (age: {backup.age_days} days)", + ) + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt for confirmation + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + # Confirm operation unless auto-approved + if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Perform cleanup + filters = {} + if older_than_days: + filters["older_than_days"] = older_than_days + if keep_count: + filters["keep_count"] = keep_count + + cleaned_count = backup_manager.clean_backups(host, **filters) + + if cleaned_count > 0: + reporter.report_result() + return EXIT_SUCCESS + else: + print(f"No backups were cleaned for host '{host}'") + return EXIT_SUCCESS + + except Exception as e: + reporter = ResultReporter("hatch mcp backup clean") + reporter.report_error("Failed to clean backups", details=[f"Reason: {str(e)}"]) + return EXIT_ERROR + + +def handle_mcp_configure(args: Namespace) -> int: + """Handle 'hatch mcp configure' command with ALL host-specific arguments. + + Host-specific arguments are accepted for all hosts. The reporting system will + show unsupported fields as "UNSUPPORTED" in the conversion report rather than + rejecting them upfront. + + The CLI creates a unified MCPServerConfig directly. Adapters handle host-specific + validation and serialization when writing to host configuration files. + + Args: + args: Parsed command-line arguments containing all configuration options + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + import shlex + from hatch.cli.cli_utils import ( + request_confirmation, + parse_env_vars, + parse_header, + parse_input, + ResultReporter, + ConsequenceType, + ) + from hatch.mcp_host_config.reporting import generate_conversion_report + + try: + # Extract arguments from Namespace + host: str = args.host + server_name: str = args.server_name + command: Optional[str] = getattr(args, "server_command", None) + cmd_args: Optional[list] = getattr(args, "args", None) + env: Optional[list] = getattr(args, "env_var", None) + url: Optional[str] = getattr(args, "url", None) + header: Optional[list] = getattr(args, "header", None) + timeout: Optional[int] = getattr(args, "timeout", None) + trust: bool = getattr(args, "trust", False) + cwd: Optional[str] = getattr(args, "cwd", None) + env_file: Optional[str] = getattr(args, "env_file", None) + http_url: Optional[str] = getattr(args, "http_url", None) + include_tools: Optional[list] = getattr(args, "include_tools", None) + exclude_tools: Optional[list] = getattr(args, "exclude_tools", None) + input_vars: Optional[list] = getattr(args, "input", None) + disabled: Optional[bool] = getattr(args, "disabled", None) + auto_approve_tools: Optional[list] = getattr(args, "auto_approve_tools", None) + disable_tools: Optional[list] = getattr(args, "disable_tools", None) + env_vars: Optional[list] = getattr(args, "env_vars", None) + startup_timeout: Optional[int] = getattr(args, "startup_timeout", None) + tool_timeout: Optional[int] = getattr(args, "tool_timeout", None) + enabled: Optional[bool] = getattr(args, "enabled", None) + bearer_token_env_var: Optional[str] = getattr( + args, "bearer_token_env_var", None + ) + env_header: Optional[list] = getattr(args, "env_header", None) + no_backup: bool = getattr(args, "no_backup", False) + dry_run: bool = getattr(args, "dry_run", False) + auto_approve: bool = getattr(args, "auto_approve", False) + + # Validate host type + try: + host_type = MCPHostType(host) # Validate and get host type enum + except ValueError: + format_validation_error( + ValidationError( + f"Invalid host '{host}'", + field="--host", + suggestion=f"Supported hosts: {', '.join(h.value for h in MCPHostType)}", + ) + ) + return EXIT_ERROR + + # Validate Claude Desktop/Code transport restrictions (Issue 2) + if host_type in (MCPHostType.CLAUDE_DESKTOP, MCPHostType.CLAUDE_CODE): + if url is not None: + format_validation_error( + ValidationError( + f"{host} does not support remote servers (--url)", + field="--url", + suggestion="Only local servers with --command are supported for this host", + ) + ) + return EXIT_ERROR + + # Validate argument dependencies + if command and header: + format_validation_error( + ValidationError( + "--header can only be used with --url or --http-url (remote servers)", + field="--header", + suggestion="Remove --header when using --command (local servers)", + ) + ) + return EXIT_ERROR + + if (url or http_url) and cmd_args: + format_validation_error( + ValidationError( + "--args can only be used with --command (local servers)", + field="--args", + suggestion="Remove --args when using --url or --http-url (remote servers)", + ) + ) + return EXIT_ERROR + + # Check if server exists (for partial update support) + manager = MCPHostConfigurationManager() + existing_config = manager.get_server_config(host, server_name) + is_update = existing_config is not None + + # Conditional validation: Create requires command OR url OR http_url, update does not + if not is_update: + if not command and not url and not http_url: + format_validation_error( + ValidationError( + "When creating a new server, you must provide a transport type", + suggestion="Use --command (local servers), --url (SSE remote servers), or --http-url (HTTP remote servers)", + ) + ) + return EXIT_ERROR + + # Parse environment variables, headers, and inputs + env_dict = parse_env_vars(env) + headers_dict = parse_header(header) + inputs_list = parse_input(input_vars) + + # Build unified configuration data + config_data = {"name": server_name} + + if command is not None: + config_data["command"] = command + if cmd_args is not None: + # Process args with shlex.split() to handle quoted strings + processed_args = [] + for arg in cmd_args: + if arg: + try: + split_args = shlex.split(arg) + processed_args.extend(split_args) + except ValueError as e: + from hatch.cli.cli_utils import Color, _colors_enabled + + if _colors_enabled(): + print( + f"{Color.YELLOW.value}[WARNING]{Color.RESET.value} Invalid quote in argument '{arg}': {e}" + ) + else: + print(f"[WARNING] Invalid quote in argument '{arg}': {e}") + processed_args.append(arg) + config_data["args"] = processed_args if processed_args else None + if env_dict: + config_data["env"] = env_dict + if url is not None: + config_data["url"] = url + if headers_dict: + config_data["headers"] = headers_dict + + # Host-specific fields (Gemini) + if timeout is not None: + config_data["timeout"] = timeout + if trust: + config_data["trust"] = trust + if cwd is not None: + config_data["cwd"] = cwd + if http_url is not None: + config_data["httpUrl"] = http_url + if include_tools is not None: + config_data["includeTools"] = include_tools + if exclude_tools is not None: + config_data["excludeTools"] = exclude_tools + + # Host-specific fields (Cursor/VS Code/LM Studio) + if env_file is not None: + config_data["envFile"] = env_file + + # Host-specific fields (VS Code) + if inputs_list is not None: + config_data["inputs"] = inputs_list + + # Host-specific fields (Kiro) + if disabled is not None: + config_data["disabled"] = disabled + if auto_approve_tools is not None: + config_data["autoApprove"] = auto_approve_tools + if disable_tools is not None: + config_data["disabledTools"] = disable_tools + + # Host-specific fields (Codex) + if env_vars is not None: + config_data["env_vars"] = env_vars + if startup_timeout is not None: + config_data["startup_timeout_sec"] = startup_timeout + if tool_timeout is not None: + config_data["tool_timeout_sec"] = tool_timeout + if enabled is not None: + config_data["enabled"] = enabled + if bearer_token_env_var is not None: + config_data["bearer_token_env_var"] = bearer_token_env_var + if env_header is not None: + env_http_headers = {} + for header_spec in env_header: + if "=" in header_spec: + key, env_var_name = header_spec.split("=", 1) + env_http_headers[key] = env_var_name + if env_http_headers: + config_data["env_http_headers"] = env_http_headers + + # Partial update merge logic + if is_update: + existing_data = existing_config.model_dump( + exclude_unset=True, exclude={"name"} + ) + + if ( + url is not None or http_url is not None + ) and existing_config.command is not None: + existing_data.pop("command", None) + existing_data.pop("args", None) + existing_data.pop("type", None) + + if command is not None and ( + existing_config.url is not None + or getattr(existing_config, "httpUrl", None) is not None + ): + existing_data.pop("url", None) + existing_data.pop("httpUrl", None) + existing_data.pop("headers", None) + existing_data.pop("type", None) + + merged_data = {**existing_data, **config_data} + config_data = merged_data + + # Create unified MCPServerConfig directly + # Adapters handle host-specific validation and serialization + server_config = MCPServerConfig(**config_data) + + # Generate conversion report + report = generate_conversion_report( + operation="update" if is_update else "create", + server_name=server_name, + target_host=host_type, + config=server_config, + old_config=existing_config if is_update else None, + dry_run=dry_run, + ) + + # Create ResultReporter for unified output + reporter = ResultReporter("hatch mcp configure", dry_run=dry_run) + reporter.add_from_conversion_report(report) + + # Display prompt and handle dry-run + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt for confirmation + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Perform configuration + mcp_manager = MCPHostConfigurationManager() + result = mcp_manager.configure_server( + server_config=server_config, hostname=host, no_backup=no_backup + ) + + if result.success: + if result.backup_path: + reporter.add(ConsequenceType.CREATE, f"Backup: {result.backup_path}") + reporter.report_result() + return EXIT_SUCCESS + else: + reporter = ResultReporter("hatch mcp configure") + reporter.report_error( + f"Failed to configure MCP server '{server_name}'", + details=[f"Host: {host}", f"Reason: {result.error_message}"], + ) + return EXIT_ERROR + + except Exception as e: + reporter = ResultReporter("hatch mcp configure") + reporter.report_error( + "Failed to configure MCP server", details=[f"Reason: {str(e)}"] + ) + return EXIT_ERROR + + +def handle_mcp_remove(args: Namespace) -> int: + """Handle 'hatch mcp remove' command. + + Removes an MCP server configuration from a specific host. + + Args: + args: Namespace with: + - host: Target host identifier (e.g., 'claude-desktop', 'vscode') + - server_name: Name of the server to remove + - no_backup: If True, skip creating backup before removal + - dry_run: If True, show what would be done without making changes + - auto_approve: If True, skip confirmation prompt + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + from hatch.cli.cli_utils import ( + request_confirmation, + ResultReporter, + ConsequenceType, + ) + + host = args.host + server_name = args.server_name + no_backup = getattr(args, "no_backup", False) + dry_run = getattr(args, "dry_run", False) + auto_approve = getattr(args, "auto_approve", False) + + try: + # Validate host type + try: + MCPHostType(host) # Validate host type enum + except ValueError: + format_validation_error( + ValidationError( + f"Invalid host '{host}'", + field="--host", + suggestion=f"Supported hosts: {', '.join(h.value for h in MCPHostType)}", + ) + ) + return EXIT_ERROR + + # Create ResultReporter for unified output + reporter = ResultReporter("hatch mcp remove", dry_run=dry_run) + reporter.add(ConsequenceType.REMOVE, f"Server '{server_name}' from '{host}'") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt for confirmation + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + # Confirm operation unless auto-approved + if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Perform removal + mcp_manager = MCPHostConfigurationManager() + result = mcp_manager.remove_server( + server_name=server_name, hostname=host, no_backup=no_backup + ) + + if result.success: + if result.backup_path: + reporter.add(ConsequenceType.CREATE, f"Backup: {result.backup_path}") + reporter.report_result() + return EXIT_SUCCESS + else: + reporter = ResultReporter("hatch mcp remove") + reporter.report_error( + f"Failed to remove MCP server '{server_name}'", + details=[f"Host: {host}", f"Reason: {result.error_message}"], + ) + return EXIT_ERROR + + except Exception as e: + reporter = ResultReporter("hatch mcp remove") + reporter.report_error( + "Failed to remove MCP server", details=[f"Reason: {str(e)}"] + ) + return EXIT_ERROR + + +def handle_mcp_remove_server(args: Namespace) -> int: + """Handle 'hatch mcp remove server' command. + + Removes an MCP server from multiple hosts. + + Args: + args: Namespace with: + - env_manager: Environment manager instance for tracking + - server_name: Name of the server to remove + - host: Comma-separated list of target hosts + - env: Environment name (for environment-based removal) + - no_backup: If True, skip creating backups + - dry_run: If True, show what would be done without making changes + - auto_approve: If True, skip confirmation prompt + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + from hatch.cli.cli_utils import ( + request_confirmation, + parse_host_list, + ResultReporter, + ConsequenceType, + ) + + env_manager = args.env_manager + server_name = args.server_name + hosts = getattr(args, "host", None) + env = getattr(args, "env", None) + no_backup = getattr(args, "no_backup", False) + dry_run = getattr(args, "dry_run", False) + auto_approve = getattr(args, "auto_approve", False) + + try: + # Determine target hosts + if hosts: + target_hosts = parse_host_list(hosts) + elif env: + # TODO: Implement environment-based server removal + format_validation_error( + ValidationError( + "Environment-based removal not yet implemented", + field="--env", + suggestion="Use --host to specify target hosts directly", + ) + ) + return EXIT_ERROR + else: + format_validation_error( + ValidationError( + "Must specify either --host or --env", + suggestion="Use --host HOST1,HOST2 or --env ENV_NAME", + ) + ) + return EXIT_ERROR + + if not target_hosts: + format_validation_error( + ValidationError( + "No valid hosts specified", + field="--host", + suggestion=f"Supported hosts: {', '.join(h.value for h in MCPHostType)}", + ) + ) + return EXIT_ERROR + + # Create ResultReporter for unified output + reporter = ResultReporter("hatch mcp remove-server", dry_run=dry_run) + for host in target_hosts: + reporter.add( + ConsequenceType.REMOVE, f"Server '{server_name}' from '{host}'" + ) + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt for confirmation + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + # Confirm operation unless auto-approved + if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Perform removal on each host + mcp_manager = MCPHostConfigurationManager() + success_count = 0 + total_count = len(target_hosts) + + # Create result reporter for actual results + result_reporter = ResultReporter("hatch mcp remove-server", dry_run=False) + + for host in target_hosts: + result = mcp_manager.remove_server( + server_name=server_name, hostname=host, no_backup=no_backup + ) + + if result.success: + result_reporter.add( + ConsequenceType.REMOVE, f"'{server_name}' from '{host}'" + ) + success_count += 1 + + # Update environment tracking for current environment only + current_env = env_manager.get_current_environment() + if current_env: + env_manager.remove_package_host_configuration( + current_env, server_name, host + ) + else: + result_reporter.add( + ConsequenceType.SKIP, + f"'{server_name}' from '{host}': {result.error_message}", + ) + + # Summary + if success_count == total_count: + result_reporter.report_result() + return EXIT_SUCCESS + elif success_count > 0: + print(f"[WARNING] Partial success: {success_count}/{total_count} hosts") + result_reporter.report_result() + return EXIT_ERROR + else: + reporter = ResultReporter("hatch mcp remove-server") + reporter.report_error( + f"Failed to remove '{server_name}' from any hosts", + details=[f"Attempted hosts: {', '.join(target_hosts)}"], + ) + return EXIT_ERROR + + except Exception as e: + reporter = ResultReporter("hatch mcp remove-server") + reporter.report_error( + "Failed to remove MCP server", details=[f"Reason: {str(e)}"] + ) + return EXIT_ERROR + + +def handle_mcp_remove_host(args: Namespace) -> int: + """Handle 'hatch mcp remove host' command. + + Removes entire host configuration (all MCP servers from a host). + + Args: + args: Namespace with: + - env_manager: Environment manager instance for tracking + - host_name: Name of the host to remove configuration from + - no_backup: If True, skip creating backup + - dry_run: If True, show what would be done without making changes + - auto_approve: If True, skip confirmation prompt + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + from hatch.cli.cli_utils import ( + request_confirmation, + ResultReporter, + ConsequenceType, + ) + + env_manager = args.env_manager + host_name = args.host_name + no_backup = getattr(args, "no_backup", False) + dry_run = getattr(args, "dry_run", False) + auto_approve = getattr(args, "auto_approve", False) + + try: + # Validate host type + try: + MCPHostType(host_name) # Validate host type enum + except ValueError: + format_validation_error( + ValidationError( + f"Invalid host '{host_name}'", + field="host_name", + suggestion=f"Supported hosts: {', '.join(h.value for h in MCPHostType)}", + ) + ) + return EXIT_ERROR + + # Create ResultReporter for unified output + reporter = ResultReporter("hatch mcp remove-host", dry_run=dry_run) + reporter.add(ConsequenceType.REMOVE, f"All servers from host '{host_name}'") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt for confirmation + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + # Confirm operation unless auto-approved + if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Perform host configuration removal + mcp_manager = MCPHostConfigurationManager() + result = mcp_manager.remove_host_configuration( + hostname=host_name, no_backup=no_backup + ) + + if result.success: + if result.backup_path: + reporter.add(ConsequenceType.CREATE, f"Backup: {result.backup_path}") + + # Update environment tracking across all environments + updates_count = env_manager.clear_host_from_all_packages_all_envs(host_name) + if updates_count > 0: + reporter.add( + ConsequenceType.UPDATE, + f"Updated {updates_count} package entries across environments", + ) + + reporter.report_result() + return EXIT_SUCCESS + else: + reporter = ResultReporter("hatch mcp remove-host") + reporter.report_error( + f"Failed to remove host configuration for '{host_name}'", + details=[f"Reason: {result.error_message}"], + ) + return EXIT_ERROR + + except Exception as e: + reporter = ResultReporter("hatch mcp remove-host") + reporter.report_error( + "Failed to remove host configuration", details=[f"Reason: {str(e)}"] + ) + return EXIT_ERROR + + +def handle_mcp_sync(args: Namespace) -> int: + """Handle 'hatch mcp sync' command. + + Synchronizes MCP server configurations from a source to target hosts. + + Args: + args: Namespace with: + - from_env: Source environment name + - from_host: Source host name + - to_host: Comma-separated list of target hosts + - servers: Comma-separated list of server names to sync + - pattern: Pattern to filter servers + - dry_run: If True, show what would be done without making changes + - auto_approve: If True, skip confirmation prompt + - no_backup: If True, skip creating backups + - detailed: If set, show field-level details (optionally filtered by consequence types) + + Returns: + int: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + """ + from hatch.cli.cli_utils import ( + request_confirmation, + parse_host_list, + ResultReporter, + ConsequenceType, + ) + + from_env = getattr(args, "from_env", None) + from_host = getattr(args, "from_host", None) + to_hosts = getattr(args, "to_host", None) + servers = getattr(args, "servers", None) + pattern = getattr(args, "pattern", None) + dry_run = getattr(args, "dry_run", False) + auto_approve = getattr(args, "auto_approve", False) + no_backup = getattr(args, "no_backup", False) + detailed = getattr(args, "detailed", None) + + # Parse detailed filter if provided + filter_types = None + if detailed: + if detailed.lower() == "all": + filter_types = None # Show all consequence types + else: + # Parse comma-separated consequence types (past tense) + filter_types = set( + t.strip().upper() for t in detailed.split(",") if t.strip() + ) + # Validate consequence types + valid_types = {ct.result_label for ct in ConsequenceType} + invalid_types = filter_types - valid_types + if invalid_types: + format_validation_error( + ValidationError( + f"Invalid consequence types: {', '.join(invalid_types)}", + field="--detailed", + suggestion=f"Valid types: {', '.join(sorted(valid_types))}", + ) + ) + return EXIT_ERROR + + try: + # Parse target hosts + if not to_hosts: + format_validation_error( + ValidationError( + "Must specify --to-host", + field="--to-host", + suggestion="Use --to-host HOST1,HOST2 or --to-host all", + ) + ) + return EXIT_ERROR + + target_hosts = parse_host_list(to_hosts) + + # Parse server filters + server_list = None + if servers: + server_list = [s.strip() for s in servers.split(",") if s.strip()] + + # Create ResultReporter for unified output + reporter = ResultReporter("hatch mcp sync", dry_run=dry_run) + + # Resolve server names for pre-prompt display + mcp_manager = MCPHostConfigurationManager() + server_names = mcp_manager.preview_sync( + from_env=from_env, + from_host=from_host, + servers=server_list, + pattern=pattern, + ) + + if server_names: + count = len(server_names) + if count > 3: + server_list_str = f"{', '.join(server_names[:3])}, ... ({count} total)" + else: + server_list_str = f"{', '.join(server_names)} ({count} total)" + reporter.add(ConsequenceType.INFO, f"Servers: {server_list_str}") + + # Build source description + source_desc = f"environment '{from_env}'" if from_env else f"host '{from_host}'" + + # Add sync consequences for preview + for target_host in target_hosts: + reporter.add(ConsequenceType.SYNC, f"{source_desc} β†’ '{target_host}'") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt for confirmation + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + # Confirm operation unless auto-approved + if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Perform synchronization (mcp_manager already created for preview) + result = mcp_manager.sync_configurations( + from_env=from_env, + from_host=from_host, + to_hosts=target_hosts, + servers=server_list, + pattern=pattern, + no_backup=no_backup, + generate_reports=detailed is not None, + ) + + if result.success: + # Create new reporter for results with actual sync details + result_reporter = ResultReporter("hatch mcp sync", dry_run=False) + + # If detailed output requested, show conversion reports + if detailed is not None: + for res in result.results: + if res.success and res.conversion_reports: + # Add detailed conversion reports for each server + for report in res.conversion_reports: + # Filter consequences if requested + if filter_types is None: + # Show all - add the full report + result_reporter.add_from_conversion_report(report) + else: + # Filter by consequence type + # Map report operation to ConsequenceType + operation_map = { + "create": ConsequenceType.CONFIGURE, + "update": ConsequenceType.CONFIGURE, + "delete": ConsequenceType.REMOVE, + "migrate": ConsequenceType.CONFIGURE, + } + resource_type = operation_map.get( + report.operation, ConsequenceType.CONFIGURE + ) + + # Check if resource type matches filter + if resource_type.result_label in filter_types: + result_reporter.add_from_conversion_report(report) + else: + # Check if any field operations match filter + field_op_map = { + "UPDATED": ConsequenceType.UPDATE, + "UNSUPPORTED": ConsequenceType.SKIP, + "UNCHANGED": ConsequenceType.UNCHANGED, + } + matching_fields = [ + field_op + for field_op in report.field_operations + if field_op_map.get( + field_op.operation, ConsequenceType.UPDATE + ).result_label + in filter_types + ] + if matching_fields: + # Create filtered report with only matching fields + from hatch.mcp_host_config.reporting import ( + ConversionReport, + ) + + filtered_report = ConversionReport( + operation=report.operation, + server_name=report.server_name, + source_host=report.source_host, + target_host=report.target_host, + field_operations=matching_fields, + dry_run=report.dry_run, + ) + result_reporter.add_from_conversion_report( + filtered_report + ) + elif not res.success: + result_reporter.add( + ConsequenceType.SKIP, + f"β†’ {res.hostname}: {res.error_message}", + ) + else: + # Standard output (no detailed) + for res in result.results: + if res.success: + result_reporter.add(ConsequenceType.SYNC, f"β†’ {res.hostname}") + else: + result_reporter.add( + ConsequenceType.SKIP, + f"β†’ {res.hostname}: {res.error_message}", + ) + + # Add sync statistics as summary details + result_reporter.add( + ConsequenceType.UPDATE, f"Servers synced: {result.servers_synced}" + ) + result_reporter.add( + ConsequenceType.UPDATE, f"Hosts updated: {result.hosts_updated}" + ) + + result_reporter.report_result() + + return EXIT_SUCCESS + else: + result_reporter = ResultReporter("hatch mcp sync") + details = [ + f"{res.hostname}: {res.error_message}" + for res in result.results + if not res.success + ] + result_reporter.report_error("Synchronization failed", details=details) + return EXIT_ERROR + + except ValueError as e: + format_validation_error(ValidationError(str(e))) + return EXIT_ERROR + except Exception as e: + reporter = ResultReporter("hatch mcp sync") + reporter.report_error("Failed to synchronize", details=[f"Reason: {str(e)}"]) + return EXIT_ERROR diff --git a/hatch/cli/cli_package.py b/hatch/cli/cli_package.py new file mode 100644 index 0000000..12738d2 --- /dev/null +++ b/hatch/cli/cli_package.py @@ -0,0 +1,584 @@ +"""Package CLI handlers for Hatch. + +This module contains handlers for package management commands. Packages are +MCP server implementations that can be installed into environments and +configured on MCP host platforms. + +Commands: + - hatch package add : Add a package to an environment + - hatch package remove : Remove a package from an environment + - hatch package list: List packages in an environment + - hatch package sync : Synchronize package MCP servers to hosts + +Package Workflow: + 1. Add package to environment: hatch package add my-mcp-server + 2. Configure on hosts: hatch mcp configure claude-desktop my-mcp-server ... + 3. Or sync automatically: hatch package sync my-mcp-server --host all + +Handler Signature: + All handlers follow: (args: Namespace) -> int + - args.env_manager: HatchEnvironmentManager instance + - Returns: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + +Internal Helpers: + _configure_packages_on_hosts(): Shared logic for configuring packages on hosts + +Example: + $ hatch package add mcp-server-fetch + $ hatch package list + $ hatch package sync mcp-server-fetch --host claude-desktop,cursor +""" + +import json +from argparse import Namespace +from pathlib import Path +from typing import TYPE_CHECKING, List, Tuple, Optional + +from hatch_validator.package.package_service import PackageService + +from hatch.cli.cli_utils import ( + EXIT_SUCCESS, + EXIT_ERROR, + request_confirmation, + parse_host_list, + get_package_mcp_server_config, + ResultReporter, + ConsequenceType, + format_warning, + format_info, + format_validation_error, + ValidationError, +) +from hatch.mcp_host_config import ( + MCPHostConfigurationManager, + MCPHostType, + MCPServerConfig, +) +from hatch.mcp_host_config.reporting import generate_conversion_report + +if TYPE_CHECKING: + from hatch.environment_manager import HatchEnvironmentManager + + +def handle_package_remove(args: Namespace) -> int: + """Handle 'hatch package remove' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - package_name: Name of package to remove + - env: Optional environment name (default: current) + - dry_run: Preview changes without execution + - auto_approve: Skip confirmation prompt + + Returns: + Exit code (0 for success, 1 for error) + + Reference: R03 Β§3.1 (03-mutation_output_specification_v0.md) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + package_name = args.package_name + env = getattr(args, "env", None) + dry_run = getattr(args, "dry_run", False) + auto_approve = getattr(args, "auto_approve", False) + + # Create reporter for unified output + reporter = ResultReporter("hatch package remove", dry_run=dry_run) + reporter.add(ConsequenceType.REMOVE, f"Package '{package_name}'") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Show prompt and request confirmation unless auto-approved + if not auto_approve: + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + if not request_confirmation("Proceed?"): + format_info("Operation cancelled") + return EXIT_SUCCESS + + if env_manager.remove_package(package_name, env): + reporter.report_result() + return EXIT_SUCCESS + else: + reporter.report_error(f"Failed to remove package '{package_name}'") + return EXIT_ERROR + + +def handle_package_list(args: Namespace) -> int: + """Handle 'hatch package list' command. + + .. deprecated:: + This command is deprecated. Use 'hatch env list' instead, + which shows packages inline with environment information. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - env: Optional environment name (default: current) + + Returns: + Exit code (0 for success) + """ + import sys + + # Emit deprecation warning to stderr + print( + "Warning: 'hatch package list' is deprecated. " + "Use 'hatch env list' instead, which shows packages inline.", + file=sys.stderr, + ) + + env_manager: "HatchEnvironmentManager" = args.env_manager + env = getattr(args, "env", None) + + packages = env_manager.list_packages(env) + + if not packages: + print(f"No packages found in environment: {env}") + return EXIT_SUCCESS + + print(f"Packages in environment '{env}':") + for pkg in packages: + print( + f"{pkg['name']} ({pkg['version']})\tHatch compliant: {pkg['hatch_compliant']}\tsource: {pkg['source']['uri']}\tlocation: {pkg['source']['path']}" + ) + return EXIT_SUCCESS + + +def _get_package_names_with_dependencies( + env_manager: "HatchEnvironmentManager", + package_path_or_name: str, + env_name: str, +) -> Tuple[str, List[str], Optional[PackageService]]: + """Get package name and its dependencies. + + Args: + env_manager: HatchEnvironmentManager instance + package_path_or_name: Package path or name + env_name: Environment name + + Returns: + Tuple of (package_name, list_of_all_package_names, package_service_or_none) + """ + package_name = package_path_or_name + package_service = None + package_names = [] + + # Check if it's a local package path + pkg_path = Path(package_path_or_name) + if pkg_path.exists() and pkg_path.is_dir(): + # Local package - load metadata from directory + with open(pkg_path / "hatch_metadata.json", "r") as f: + metadata = json.load(f) + package_service = PackageService(metadata) + package_name = package_service.get_field("name") + else: + # Registry package - get metadata from environment manager + try: + env_data = env_manager.get_environment_data(env_name) + if env_data: + # Find the package in the environment + for pkg in env_data.packages: + if pkg.name == package_name: + # Create a minimal metadata structure for PackageService + metadata = { + "name": pkg.name, + "version": pkg.version, + "dependencies": {}, + } + package_service = PackageService(metadata) + break + + if package_service is None: + format_warning( + f"Could not find package '{package_name}' in environment '{env_name}'", + suggestion="Skipping dependency analysis", + ) + except Exception as e: + format_warning( + f"Could not load package metadata for '{package_name}': {e}", + suggestion="Skipping dependency analysis", + ) + + # Get dependency names if we have package service + if package_service: + # Get Hatch dependencies + dependencies = package_service.get_dependencies() + hatch_deps = dependencies.get("hatch", []) + package_names = [dep.get("name") for dep in hatch_deps if dep.get("name")] + + # Resolve local dependency paths to actual names + for i in range(len(package_names)): + dep_path = Path(package_names[i]) + if dep_path.exists() and dep_path.is_dir(): + try: + with open(dep_path / "hatch_metadata.json", "r") as f: + dep_metadata = json.load(f) + dep_service = PackageService(dep_metadata) + package_names[i] = dep_service.get_field("name") + except Exception as e: + format_warning( + f"Could not resolve dependency path '{package_names[i]}': {e}" + ) + + # Add the main package to the list + package_names.append(package_name) + + return package_name, package_names, package_service + + +def _configure_packages_on_hosts( + env_manager: "HatchEnvironmentManager", + mcp_manager: MCPHostConfigurationManager, + env_name: str, + package_names: List[str], + hosts: List[str], + no_backup: bool = False, + dry_run: bool = False, + reporter: Optional[ResultReporter] = None, +) -> Tuple[int, int]: + """Configure MCP servers for packages on specified hosts. + + This is shared logic used by both package add and package sync commands. + + Args: + env_manager: HatchEnvironmentManager instance + mcp_manager: MCPHostConfigurationManager instance + env_name: Environment name + package_names: List of package names to configure + hosts: List of host names to configure on + no_backup: Skip backup creation + dry_run: Preview only, don't execute + reporter: Optional ResultReporter for unified output + + Returns: + Tuple of (success_count, total_operations) + """ + # Get MCP server configurations for all packages + server_configs: List[Tuple[str, MCPServerConfig]] = [] + for pkg_name in package_names: + try: + config = get_package_mcp_server_config(env_manager, env_name, pkg_name) + server_configs.append((pkg_name, config)) + except Exception as e: + format_warning( + f"Could not get MCP configuration for package '{pkg_name}': {e}" + ) + + if not server_configs: + return 0, 0 + + total_operations = len(server_configs) * len(hosts) + success_count = 0 + + for host in hosts: + try: + # Convert string to MCPHostType enum + host_type = MCPHostType(host) + + for pkg_name, server_config in server_configs: + try: + # Generate conversion report for field-level details + report = generate_conversion_report( + operation="create", + server_name=server_config.name, + target_host=host_type, + config=server_config, + dry_run=dry_run, + ) + + # Add to reporter if provided + if reporter: + reporter.add_from_conversion_report(report) + + if dry_run: + success_count += 1 + continue + + # Pass MCPServerConfig directly - adapters handle serialization + result = mcp_manager.configure_server( + hostname=host, + server_config=server_config, + no_backup=no_backup, + ) + + if result.success: + success_count += 1 + + # Update package metadata with host configuration tracking + try: + server_config_dict = { + "name": server_config.name, + "command": server_config.command, + "args": server_config.args, + } + + env_manager.update_package_host_configuration( + env_name=env_name, + package_name=pkg_name, + hostname=host, + server_config=server_config_dict, + ) + except Exception as e: + format_warning( + f"Failed to update package metadata for {pkg_name}: {e}" + ) + else: + format_warning( + f"Failed to configure {server_config.name} ({pkg_name}) on {host}", + suggestion=f"Reason: {result.error_message}", + ) + + except Exception as e: + format_warning( + f"Error configuring {server_config.name} ({pkg_name}) on {host}", + suggestion=f"Exception: {e}", + ) + + except ValueError as e: + format_validation_error( + ValidationError( + f"Invalid host '{host}'", field="--host", suggestion=str(e) + ) + ) + continue + + return success_count, total_operations + + +def handle_package_add(args: Namespace) -> int: + """Handle 'hatch package add' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - mcp_manager: MCPHostConfigurationManager instance + - package_path_or_name: Package path or name + - env: Optional environment name + - version: Optional version + - force_download: Force download even if cached + - refresh_registry: Force registry refresh + - auto_approve: Skip confirmation prompts + - host: Optional comma-separated host list for MCP configuration + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + mcp_manager: MCPHostConfigurationManager = args.mcp_manager + + package_path_or_name = args.package_path_or_name + env = getattr(args, "env", None) + version = getattr(args, "version", None) + force_download = getattr(args, "force_download", False) + refresh_registry = getattr(args, "refresh_registry", False) + auto_approve = getattr(args, "auto_approve", False) + host_arg = getattr(args, "host", None) + dry_run = getattr(args, "dry_run", False) + + # Create reporter for unified output + reporter = ResultReporter("hatch package add", dry_run=dry_run) + + # Add package to environment + reporter.add(ConsequenceType.ADD, f"Package '{package_path_or_name}'") + + if not env_manager.add_package_to_environment( + package_path_or_name, + env, + version, + force_download, + refresh_registry, + auto_approve, + ): + reporter.report_error(f"Failed to add package '{package_path_or_name}'") + return EXIT_ERROR + + # Handle MCP host configuration if requested + if host_arg: + try: + hosts = parse_host_list(host_arg) + env_name = env or env_manager.get_current_environment() + + package_name, package_names, _ = _get_package_names_with_dependencies( + env_manager, package_path_or_name, env_name + ) + + success_count, total = _configure_packages_on_hosts( + env_manager=env_manager, + mcp_manager=mcp_manager, + env_name=env_name, + package_names=package_names, + hosts=hosts, + no_backup=False, # Always backup when adding packages + dry_run=dry_run, + reporter=reporter, + ) + + except ValueError as e: + format_warning(f"MCP host configuration failed: {e}") + # Don't fail the entire operation for MCP configuration issues + + # Report results + reporter.report_result() + return EXIT_SUCCESS + + +def handle_package_sync(args: Namespace) -> int: + """Handle 'hatch package sync' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - mcp_manager: MCPHostConfigurationManager instance + - package_name: Package name to sync + - host: Comma-separated host list (required) + - env: Optional environment name + - dry_run: Preview only + - auto_approve: Skip confirmation + - no_backup: Skip backup creation + + Returns: + Exit code (0 for success, 1 for error) + """ + env_manager: "HatchEnvironmentManager" = args.env_manager + mcp_manager: MCPHostConfigurationManager = args.mcp_manager + + package_name = args.package_name + host_arg = args.host + env = getattr(args, "env", None) + dry_run = getattr(args, "dry_run", False) + auto_approve = getattr(args, "auto_approve", False) + no_backup = getattr(args, "no_backup", False) + + # Create reporter for unified output + reporter = ResultReporter("hatch package sync", dry_run=dry_run) + + try: + # Parse host list + hosts = parse_host_list(host_arg) + env_name = env or env_manager.get_current_environment() + + # Get all packages to sync (main package + dependencies) + package_names = [package_name] + + # Try to get dependencies for the main package + try: + env_data = env_manager.get_environment_data(env_name) + if env_data: + # Find the main package in the environment + main_package = None + for pkg in env_data.packages: + if pkg.name == package_name: + main_package = pkg + break + + if main_package: + # Create a minimal metadata structure for PackageService + metadata = { + "name": main_package.name, + "version": main_package.version, + "dependencies": {}, + } + package_service = PackageService(metadata) + + # Get Hatch dependencies + dependencies = package_service.get_dependencies() + hatch_deps = dependencies.get("hatch", []) + dep_names = [ + dep.get("name") for dep in hatch_deps if dep.get("name") + ] + + # Add dependencies to the sync list (before main package) + package_names = dep_names + [package_name] + else: + format_warning( + f"Package '{package_name}' not found in environment '{env_name}'", + suggestion="Syncing only the specified package", + ) + else: + format_warning( + f"Could not access environment '{env_name}'", + suggestion="Syncing only the specified package", + ) + except Exception as e: + format_warning( + f"Could not analyze dependencies for '{package_name}': {e}", + suggestion="Syncing only the specified package", + ) + + # Get MCP server configurations for all packages + server_configs: List[Tuple[str, MCPServerConfig]] = [] + for pkg_name in package_names: + try: + config = get_package_mcp_server_config(env_manager, env_name, pkg_name) + server_configs.append((pkg_name, config)) + except Exception as e: + format_warning( + f"Could not get MCP configuration for package '{pkg_name}': {e}" + ) + + if not server_configs: + reporter.report_error( + f"No MCP server configurations found for package '{package_name}' or its dependencies" + ) + return EXIT_ERROR + + # Build consequences for preview/confirmation + for pkg_name, config in server_configs: + for host in hosts: + try: + host_type = MCPHostType(host) + report = generate_conversion_report( + operation="create", + server_name=config.name, + target_host=host_type, + config=config, + dry_run=dry_run, + ) + reporter.add_from_conversion_report(report) + except ValueError: + reporter.add(ConsequenceType.SKIP, f"Invalid host '{host}'") + + # Show preview and get confirmation + prompt = reporter.report_prompt() + if prompt: + print(prompt) + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + # Confirm operation unless auto-approved + if not request_confirmation("Proceed?", auto_approve): + format_info("Operation cancelled") + return EXIT_SUCCESS + + # Perform synchronization (reporter already has consequences from preview) + success_count, total_operations = _configure_packages_on_hosts( + env_manager=env_manager, + mcp_manager=mcp_manager, + env_name=env_name, + package_names=[pkg_name for pkg_name, _ in server_configs], + hosts=hosts, + no_backup=no_backup, + dry_run=False, + reporter=None, # Don't add again, we already have consequences + ) + + # Report results + reporter.report_result() + + if success_count == total_operations: + return EXIT_SUCCESS + elif success_count > 0: + return EXIT_ERROR + else: + return EXIT_ERROR + + except ValueError as e: + reporter.report_error(str(e)) + return EXIT_ERROR diff --git a/hatch/cli/cli_system.py b/hatch/cli/cli_system.py new file mode 100644 index 0000000..104eff5 --- /dev/null +++ b/hatch/cli/cli_system.py @@ -0,0 +1,137 @@ +"""System CLI handlers for Hatch. + +This module contains handlers for system-level commands that operate on +packages as a whole rather than within environments. + +Commands: + - hatch create : Create a new package template from scratch + - hatch validate : Validate a package against the Hatch schema + +Package Creation: + The create command generates a complete package template with: + - pyproject.toml with Hatch metadata + - Source directory structure + - README and LICENSE files + - Basic MCP server implementation + +Package Validation: + The validate command checks: + - pyproject.toml structure and required fields + - Hatch-specific metadata (mcp_server entry points) + - Package dependencies and version constraints + +Handler Signature: + All handlers follow: (args: Namespace) -> int + Returns: EXIT_SUCCESS (0) on success, EXIT_ERROR (1) on failure + +Example: + $ hatch create my-mcp-server --description "My custom MCP server" + $ hatch validate ./my-mcp-server +""" + +from argparse import Namespace +from pathlib import Path + +from hatch_validator import HatchPackageValidator + +from hatch.cli.cli_utils import ( + EXIT_SUCCESS, + EXIT_ERROR, + ResultReporter, + ConsequenceType, +) +from hatch.template_generator import create_package_template + + +def handle_create(args: Namespace) -> int: + """Handle 'hatch create' command. + + Args: + args: Namespace with: + - name: Package name + - dir: Target directory (default: current directory) + - description: Package description (optional) + + Returns: + Exit code (0 for success, 1 for error) + """ + target_dir = Path(args.dir).resolve() + description = getattr(args, "description", "") + dry_run = getattr(args, "dry_run", False) + + # Create reporter for unified output + reporter = ResultReporter("hatch create", dry_run=dry_run) + reporter.add(ConsequenceType.CREATE, f"Package '{args.name}' at {target_dir}") + + if dry_run: + reporter.report_result() + return EXIT_SUCCESS + + try: + create_package_template( + target_dir=target_dir, + package_name=args.name, + description=description, + ) + reporter.report_result() + return EXIT_SUCCESS + except Exception as e: + reporter.report_error( + "Failed to create package template", details=[f"Reason: {e}"] + ) + return EXIT_ERROR + + +def handle_validate(args: Namespace) -> int: + """Handle 'hatch validate' command. + + Args: + args: Namespace with: + - env_manager: HatchEnvironmentManager instance + - package_dir: Path to package directory + + Returns: + Exit code (0 for success, 1 for error) + """ + from hatch.environment_manager import HatchEnvironmentManager + + env_manager: HatchEnvironmentManager = args.env_manager + package_path = Path(args.package_dir).resolve() + + # Create reporter for unified output + reporter = ResultReporter("hatch validate", dry_run=False) + + # Create validator with registry data from environment manager + validator = HatchPackageValidator( + version="latest", + allow_local_dependencies=True, + registry_data=env_manager.registry_data, + ) + + # Validate the package + is_valid, validation_results = validator.validate_package(package_path) + + if is_valid: + reporter.add(ConsequenceType.VALIDATE, f"Package '{package_path.name}'") + reporter.report_result() + return EXIT_SUCCESS + else: + # Collect detailed validation errors + error_details = [f"Package: {package_path}"] + + if validation_results and isinstance(validation_results, dict): + for category, result in validation_results.items(): + if ( + category != "valid" + and category != "metadata" + and isinstance(result, dict) + ): + if not result.get("valid", True) and result.get("errors"): + error_details.append( + f"{category.replace('_', ' ').title()} errors:" + ) + for error in result["errors"]: + error_details.append(f" - {error}") + + reporter.report_error("Package validation failed", details=error_details) + return EXIT_ERROR diff --git a/hatch/cli/cli_utils.py b/hatch/cli/cli_utils.py new file mode 100644 index 0000000..9868f15 --- /dev/null +++ b/hatch/cli/cli_utils.py @@ -0,0 +1,1280 @@ +"""Shared utilities for Hatch CLI. + +This module provides common utilities used across CLI handlers, extracted +from the monolithic cli_hatch.py to enable cleaner handler-based architecture +and easier testing. + +Constants: + EXIT_SUCCESS (int): Exit code for successful operations (0) + EXIT_ERROR (int): Exit code for failed operations (1) + +Classes: + Color: ANSI color codes with brightness variants for tense distinction + +Functions: + get_hatch_version(): Retrieve version from package metadata + request_confirmation(): Interactive user confirmation with auto-approve support + parse_env_vars(): Parse KEY=VALUE environment variable arguments + parse_header(): Parse KEY=VALUE HTTP header arguments + parse_input(): Parse VSCode input configurations + parse_host_list(): Parse comma-separated host list or 'all' + get_package_mcp_server_config(): Extract MCP server config from package metadata + _colors_enabled(): Check if color output should be enabled + +Example: + >>> from hatch.cli.cli_utils import EXIT_SUCCESS, EXIT_ERROR, request_confirmation + >>> if request_confirmation("Proceed?", auto_approve=False): + ... return EXIT_SUCCESS + ... else: + ... return EXIT_ERROR + + >>> from hatch.cli.cli_utils import parse_env_vars + >>> env_dict = parse_env_vars(["API_KEY=secret", "DEBUG=true"]) + >>> # Returns: {"API_KEY": "secret", "DEBUG": "true"} +""" + +from enum import Enum +from importlib.metadata import PackageNotFoundError, version + +# Standard library imports +import json +import os +import os as _os +import sys +from dataclasses import dataclass, field +from pathlib import Path +from typing import List, Literal, Optional, Tuple, Union + +# Local imports +from hatch.environment_manager import HatchEnvironmentManager +from hatch.mcp_host_config import MCPHostRegistry, MCPHostType, MCPServerConfig +from hatch.mcp_host_config.reporting import ConversionReport + +# ============================================================================= +# Color Infrastructure for CLI Output +# ============================================================================= + + +def _supports_truecolor() -> bool: + """Detect if terminal supports 24-bit true color. + + Checks environment variables and terminal identifiers to determine + if the terminal supports true color (24-bit RGB) output. + + Reference: R12 Β§3.1 (12-enhancing_colors_v0.md) + + Detection Logic: + 1. COLORTERM='truecolor' or '24bit' β†’ True + 2. TERM contains 'truecolor' or '24bit' β†’ True + 3. TERM_PROGRAM in known true color terminals β†’ True + 4. WT_SESSION set (Windows Terminal) β†’ True + 5. Otherwise β†’ False (fallback to 16-color) + + Returns: + bool: True if terminal supports true color, False otherwise. + + Example: + >>> if _supports_truecolor(): + ... # Use 24-bit RGB color codes + ... color = "\\033[38;2;128;201;144m" + ... else: + ... # Use 16-color ANSI codes + ... color = "\\033[92m" + """ + # Check COLORTERM for 'truecolor' or '24bit' + colorterm = _os.environ.get("COLORTERM", "") + if colorterm in ("truecolor", "24bit"): + return True + + # Check TERM for truecolor indicators + term = _os.environ.get("TERM", "") + if "truecolor" in term or "24bit" in term: + return True + + # Check TERM_PROGRAM for known true color terminals + term_program = _os.environ.get("TERM_PROGRAM", "") + if term_program in ("iTerm.app", "Apple_Terminal", "vscode", "Hyper"): + return True + + # Check WT_SESSION for Windows Terminal + if _os.environ.get("WT_SESSION"): + return True + + return False + + +# Module-level constant for true color support detection +# Evaluated once at module load time +TRUECOLOR = _supports_truecolor() + + +class Color(Enum): + """HCL color palette with true color support and 16-color fallback. + + Uses a qualitative HCL palette with equal perceived brightness + for accessibility and visual harmony. True color (24-bit) is used + when supported, falling back to standard 16-color ANSI codes. + + Reference: R12 Β§3.2 (12-enhancing_colors_v0.md) + Reference: R06 Β§3.1 (06-dependency_analysis_v0.md) + Reference: R03 Β§4 (03-mutation_output_specification_v0.md) + + HCL Palette Values: + GREEN #80C990 β†’ rgb(128, 201, 144) + RED #EFA6A2 β†’ rgb(239, 166, 162) + YELLOW #C8C874 β†’ rgb(200, 200, 116) + BLUE #A3B8EF β†’ rgb(163, 184, 239) + MAGENTA #E6A3DC β†’ rgb(230, 163, 220) + CYAN #50CACD β†’ rgb(80, 202, 205) + GRAY #808080 β†’ rgb(128, 128, 128) + AMBER #A69460 β†’ rgb(166, 148, 96) + + Color Semantics: + Green β†’ Constructive (CREATE, ADD, CONFIGURE, INSTALL, INITIALIZE) + Blue β†’ Recovery (RESTORE) + Red β†’ Destructive (REMOVE, DELETE, CLEAN) + Yellow β†’ Modification (SET, UPDATE) + Magenta β†’ Transfer (SYNC) + Cyan β†’ Informational (VALIDATE) + Gray β†’ No-op (SKIP, EXISTS, UNCHANGED) + Amber β†’ Entity highlighting (show commands) + + Example: + >>> from hatch.cli.cli_utils import Color, _colors_enabled + >>> if _colors_enabled(): + ... print(f"{Color.GREEN.value}Success{Color.RESET.value}") + ... else: + ... print("Success") + """ + + # === Bright colors (execution results - past tense) === + + # Green #80C990 - CREATE, ADD, CONFIGURE, INSTALL, INITIALIZE + GREEN = "\033[38;2;128;201;144m" if TRUECOLOR else "\033[92m" + + # Red #EFA6A2 - REMOVE, DELETE, CLEAN + RED = "\033[38;2;239;166;162m" if TRUECOLOR else "\033[91m" + + # Yellow #C8C874 - SET, UPDATE + YELLOW = "\033[38;2;200;200;116m" if TRUECOLOR else "\033[93m" + + # Blue #A3B8EF - RESTORE + BLUE = "\033[38;2;163;184;239m" if TRUECOLOR else "\033[94m" + + # Magenta #E6A3DC - SYNC + MAGENTA = "\033[38;2;230;163;220m" if TRUECOLOR else "\033[95m" + + # Cyan #50CACD - VALIDATE + CYAN = "\033[38;2;80;202;205m" if TRUECOLOR else "\033[96m" + + # === Dim colors (confirmation prompts - present tense) === + + # Aquamarine #5ACCAF (green shifted) + GREEN_DIM = "\033[38;2;90;204;175m" if TRUECOLOR else "\033[2;32m" + + # Orange #E0AF85 (red shifted) + RED_DIM = "\033[38;2;224;175;133m" if TRUECOLOR else "\033[2;31m" + + # Amber #A69460 (yellow shifted) + YELLOW_DIM = "\033[38;2;166;148;96m" if TRUECOLOR else "\033[2;33m" + + # Violet #CCACED (blue shifted) + BLUE_DIM = "\033[38;2;204;172;237m" if TRUECOLOR else "\033[2;34m" + + # Rose #F2A1C2 (magenta shifted) + MAGENTA_DIM = "\033[38;2;242;161;194m" if TRUECOLOR else "\033[2;35m" + + # Azure #74C3E4 (cyan shifted) + CYAN_DIM = "\033[38;2;116;195;228m" if TRUECOLOR else "\033[2;36m" + + # === Utility colors === + + # Gray #808080 - SKIP, EXISTS, UNCHANGED + GRAY = "\033[38;2;128;128;128m" if TRUECOLOR else "\033[90m" + + # Amber #A69460 - Entity name highlighting (NEW) + AMBER = "\033[38;2;166;148;96m" if TRUECOLOR else "\033[33m" + + # Reset + RESET = "\033[0m" + + +def _supports_unicode() -> bool: + """Check if terminal supports UTF-8 for unicode symbols. + + Used to determine whether to use βœ“/βœ— symbols or ASCII fallback (+/x) + in partial success reporting. + + Reference: R13 Β§12.3 (13-error_message_formatting_v0.md) + + Returns: + bool: True if terminal supports UTF-8, False otherwise. + + Example: + >>> if _supports_unicode(): + ... success_symbol = "βœ“" + ... else: + ... success_symbol = "+" + """ + import locale + + encoding = locale.getpreferredencoding(False) + return encoding.lower() in ("utf-8", "utf8") + + +def _colors_enabled() -> bool: + """Check if color output should be enabled. + + Colors are disabled when: + - NO_COLOR environment variable is set to a non-empty value + - stdout is not a TTY (e.g., piped output, CI environment) + + Reference: R05 Β§3.4 (05-test_definition_v0.md) + + Returns: + bool: True if colors should be enabled, False otherwise. + + Example: + >>> if _colors_enabled(): + ... print(f"{Color.GREEN.value}colored{Color.RESET.value}") + ... else: + ... print("plain") + """ + import os + import sys + + # Check NO_COLOR environment variable (https://no-color.org/) + no_color = os.environ.get("NO_COLOR", "") + if no_color: # Any non-empty value disables colors + return False + + # Check if stdout is a TTY + if not sys.stdout.isatty(): + return False + + return True + + +def highlight(text: str) -> str: + """Apply highlight formatting (bold + amber) to entity names. + + Used in show commands to emphasize host and server names for + quick visual scanning of detailed output. + + Reference: R12 Β§3.3 (12-enhancing_colors_v0.md) + Reference: R11 Β§3.2 (11-enhancing_show_command_v0.md) + + Args: + text: The entity name to highlight + + Returns: + str: Text with bold + amber formatting if colors enabled, + otherwise plain text. + + Example: + >>> print(f"MCP Host: {highlight('claude-desktop')}") + MCP Host: claude-desktop # (bold + amber in TTY) + """ + if _colors_enabled(): + # Bold (\033[1m) + Amber color + return f"\033[1m{Color.AMBER.value}{text}{Color.RESET.value}" + return text + + +class ConsequenceType(Enum): + """Action types with dual-tense labels and semantic colors. + + Each consequence type has: + - prompt_label: Present tense for confirmation prompts (e.g., "CREATE") + - result_label: Past tense for execution results (e.g., "CREATED") + - prompt_color: Dim color for prompts + - result_color: Bright color for results + + Reference: R06 Β§3.2 (06-dependency_analysis_v0.md) + Reference: R03 Β§2 (03-mutation_output_specification_v0.md) + + Categories: + Constructive (Green): CREATE, ADD, CONFIGURE, INSTALL, INITIALIZE + Recovery (Blue): RESTORE + Destructive (Red): REMOVE, DELETE, CLEAN + Modification (Yellow): SET, UPDATE + Transfer (Magenta): SYNC + Informational (Cyan): VALIDATE + No-op (Gray): SKIP, EXISTS, UNCHANGED + + Example: + >>> ct = ConsequenceType.CREATE + >>> print(f"[{ct.prompt_label}]") # [CREATE] + >>> print(f"[{ct.result_label}]") # [CREATED] + """ + + # Value format: (prompt_label, result_label, prompt_color, result_color) + + # Constructive actions (Green) + CREATE = ("CREATE", "CREATED", Color.GREEN_DIM, Color.GREEN) + ADD = ("ADD", "ADDED", Color.GREEN_DIM, Color.GREEN) + CONFIGURE = ("CONFIGURE", "CONFIGURED", Color.GREEN_DIM, Color.GREEN) + INSTALL = ("INSTALL", "INSTALLED", Color.GREEN_DIM, Color.GREEN) + INITIALIZE = ("INITIALIZE", "INITIALIZED", Color.GREEN_DIM, Color.GREEN) + + # Recovery actions (Blue) + RESTORE = ("RESTORE", "RESTORED", Color.BLUE_DIM, Color.BLUE) + + # Destructive actions (Red) + REMOVE = ("REMOVE", "REMOVED", Color.RED_DIM, Color.RED) + DELETE = ("DELETE", "DELETED", Color.RED_DIM, Color.RED) + CLEAN = ("CLEAN", "CLEANED", Color.RED_DIM, Color.RED) + + # Modification actions (Yellow) + SET = ("SET", "SET", Color.YELLOW_DIM, Color.YELLOW) # Irregular: no change + UPDATE = ("UPDATE", "UPDATED", Color.YELLOW_DIM, Color.YELLOW) + + # Transfer actions (Magenta) + SYNC = ("SYNC", "SYNCED", Color.MAGENTA_DIM, Color.MAGENTA) + + # Informational actions (Cyan) + VALIDATE = ("VALIDATE", "VALIDATED", Color.CYAN_DIM, Color.CYAN) + INFO = ("INFO", "INFO", Color.CYAN_DIM, Color.CYAN) + + # No-op actions (Gray) - same color for prompt and result + SKIP = ("SKIP", "SKIPPED", Color.GRAY, Color.GRAY) + EXISTS = ("EXISTS", "EXISTS", Color.GRAY, Color.GRAY) # Irregular: no change + UNCHANGED = ( + "UNCHANGED", + "UNCHANGED", + Color.GRAY, + Color.GRAY, + ) # Irregular: no change + + @property + def prompt_label(self) -> str: + """Present tense label for confirmation prompts.""" + return self.value[0] + + @property + def result_label(self) -> str: + """Past tense label for execution results.""" + return self.value[1] + + @property + def prompt_color(self) -> Color: + """Dim color for confirmation prompts.""" + return self.value[2] + + @property + def result_color(self) -> Color: + """Bright color for execution results.""" + return self.value[3] + + +# ============================================================================= +# ValidationError Exception for Structured Error Reporting +# ============================================================================= + + +class ValidationError(Exception): + """Validation error with structured context. + + Provides structured error information for input validation failures, + including optional field name and suggestion for resolution. + + Reference: R13 Β§4.2.2 (13-error_message_formatting_v0.md) + + Attributes: + message: Human-readable error description + field: Optional field/argument name that caused the error + suggestion: Optional suggestion for resolving the error + + Example: + >>> raise ValidationError( + ... "Invalid host 'vsc'", + ... field="--host", + ... suggestion="Supported hosts: claude-desktop, vscode, cursor" + ... ) + """ + + def __init__(self, message: str, field: str = None, suggestion: str = None): + """Initialize ValidationError. + + Args: + message: Human-readable error description + field: Optional field/argument name that caused the error + suggestion: Optional suggestion for resolving the error + """ + self.message = message + self.field = field + self.suggestion = suggestion + super().__init__(message) + + +@dataclass +class Consequence: + """Data model for a single consequence (resource or field level). + + Consequences represent actions that will be or have been performed. + They can be nested to show resource-level actions with field-level details. + + Reference: R06 Β§3.3 (06-dependency_analysis_v0.md) + Reference: R04 Β§5.1 (04-reporting_infrastructure_coexistence_v0.md) + + Attributes: + type: The ConsequenceType indicating the action category + message: Human-readable description of the consequence + children: Nested consequences (e.g., field-level details under resource) + + Invariants: + - children only populated for resource-level consequences + - field-level consequences have empty children list + - nesting limited to 2 levels (resource β†’ field) + + Example: + >>> parent = Consequence( + ... type=ConsequenceType.CONFIGURE, + ... message="Server 'weather' on 'claude-desktop'", + ... children=[ + ... Consequence(ConsequenceType.UPDATE, "command: None β†’ 'python'"), + ... Consequence(ConsequenceType.SKIP, "timeout: unsupported"), + ... ] + ... ) + """ + + type: ConsequenceType + message: str + children: List["Consequence"] = field(default_factory=list) + + +class ResultReporter: + """Unified rendering system for all CLI output. + + Tracks consequences and renders them with tense-aware, color-coded output. + Present tense (dim colors) for confirmation prompts, past tense (bright colors) + for execution results. + + Reference: R06 Β§3.4 (06-dependency_analysis_v0.md) + Reference: R04 Β§5.2 (04-reporting_infrastructure_coexistence_v0.md) + Reference: R01 Β§8.2 (01-cli_output_analysis_v2.md) + + Attributes: + command_name: Display name for the command (e.g., "hatch mcp configure") + dry_run: If True, append "- DRY RUN" suffix to result labels + consequences: List of tracked consequences in order of addition + + Invariants: + - consequences list is append-only + - report_prompt() and report_result() are idempotent + - Order of add() calls determines output order + + Example: + >>> reporter = ResultReporter("hatch env create", dry_run=False) + >>> reporter.add(ConsequenceType.CREATE, "Environment 'dev'") + >>> reporter.add(ConsequenceType.CREATE, "Python environment (3.11)") + >>> prompt = reporter.report_prompt() # Present tense, dim colors + >>> # ... user confirms ... + >>> reporter.report_result() # Past tense, bright colors + """ + + def __init__(self, command_name: str, dry_run: bool = False): + """Initialize ResultReporter. + + Args: + command_name: Display name for the command + dry_run: If True, results show "- DRY RUN" suffix + """ + self._command_name = command_name + self._dry_run = dry_run + self._consequences: List[Consequence] = [] + + @property + def command_name(self) -> str: + """Display name for the command.""" + return self._command_name + + @property + def dry_run(self) -> bool: + """Whether this is a dry-run preview.""" + return self._dry_run + + @property + def consequences(self) -> List[Consequence]: + """List of tracked consequences in order of addition.""" + return self._consequences + + def add( + self, + consequence_type: ConsequenceType, + message: str, + children: Optional[List[Consequence]] = None, + ) -> None: + """Add a consequence with optional nested children. + + Args: + consequence_type: The type of action + message: Human-readable description + children: Optional nested consequences (e.g., field-level details) + + Invariants: + - Order of add() calls determines output order + - Children inherit parent's tense during rendering + """ + consequence = Consequence( + type=consequence_type, message=message, children=children or [] + ) + self._consequences.append(consequence) + + def add_from_conversion_report(self, report: "ConversionReport") -> None: + """Convert ConversionReport field operations to nested consequences. + + Maps ConversionReport data to the unified consequence model: + - report.operation β†’ resource ConsequenceType + - field_op "UPDATED" β†’ ConsequenceType.UPDATE + - field_op "UNSUPPORTED" β†’ ConsequenceType.SKIP + - field_op "UNCHANGED" β†’ ConsequenceType.UNCHANGED + + Reference: R06 Β§3.5 (06-dependency_analysis_v0.md) + Reference: R04 Β§1.2 (04-reporting_infrastructure_coexistence_v0.md) + + Args: + report: ConversionReport with field operations to convert + + Invariants: + - All field operations become children of resource consequence + - UNSUPPORTED fields include "(unsupported by host)" suffix + """ + # Import here to avoid circular dependency + + # Map report.operation to resource ConsequenceType + operation_map = { + "create": ConsequenceType.CONFIGURE, + "update": ConsequenceType.CONFIGURE, + "delete": ConsequenceType.REMOVE, + "migrate": ConsequenceType.CONFIGURE, + } + resource_type = operation_map.get(report.operation, ConsequenceType.CONFIGURE) + + # Build resource message + resource_message = ( + f"Server '{report.server_name}' on '{report.target_host.value}'" + ) + + # Map field operations to child consequences + field_op_map = { + "UPDATED": ConsequenceType.UPDATE, + "UNSUPPORTED": ConsequenceType.SKIP, + "UNCHANGED": ConsequenceType.UNCHANGED, + } + + children = [] + for field_op in report.field_operations: + child_type = field_op_map.get(field_op.operation, ConsequenceType.UPDATE) + + # Format field message based on operation type + if field_op.operation == "UPDATED": + child_message = f"{field_op.field_name}: {repr(field_op.old_value)} β†’ {repr(field_op.new_value)}" + elif field_op.operation == "UNSUPPORTED": + child_message = f"{field_op.field_name}: (unsupported by host)" + else: # UNCHANGED + child_message = f"{field_op.field_name}: {repr(field_op.new_value)}" + + children.append(Consequence(type=child_type, message=child_message)) + + # Add the resource consequence with children + self.add(resource_type, resource_message, children=children) + + def _format_consequence( + self, consequence: Consequence, use_result_tense: bool, indent: int = 2 + ) -> str: + """Format a single consequence with color and tense. + + Args: + consequence: The consequence to format + use_result_tense: True for past tense (result), False for present (prompt) + indent: Number of spaces for indentation + + Returns: + Formatted string with optional ANSI colors + """ + ct = consequence.type + label = ct.result_label if use_result_tense else ct.prompt_label + color = ct.result_color if use_result_tense else ct.prompt_color + + # Add dry-run suffix for results + if use_result_tense and self._dry_run: + label = f"{label} - DRY RUN" + + # Format with or without colors + indent_str = " " * indent + if _colors_enabled(): + line = f"{indent_str}{color.value}[{label}]{Color.RESET.value} {consequence.message}" + else: + line = f"{indent_str}[{label}] {consequence.message}" + + return line + + def report_prompt(self) -> str: + """Generate confirmation prompt (present tense, dim colors). + + Output format: + {command_name}: + [VERB] resource message + [VERB] field message + [VERB] field message + + Returns: + Formatted prompt string, empty string if no consequences. + + Invariants: + - All consequences shown (including UNCHANGED, SKIP) + - Empty string if no consequences + """ + if not self._consequences: + return "" + + lines = [f"{self._command_name}:"] + + for consequence in self._consequences: + lines.append(self._format_consequence(consequence, use_result_tense=False)) + for child in consequence.children: + lines.append( + self._format_consequence(child, use_result_tense=False, indent=4) + ) + + return "\n".join(lines) + + def report_result(self) -> None: + """Print execution results (past tense, bright colors). + + Output format: + [SUCCESS] summary (or [DRY RUN] for dry-run mode) + [VERB-ED] resource message + [VERB-ED] field message (only changed fields) + + Invariants: + - UNCHANGED and SKIP fields may be omitted from result (noise reduction) + - Dry-run appends "- DRY RUN" suffix + - No output if consequences list is empty + """ + if not self._consequences: + return + + # Print header + if self._dry_run: + if _colors_enabled(): + print( + f"{Color.CYAN.value}[DRY RUN]{Color.RESET.value} Preview of changes:" + ) + else: + print("[DRY RUN] Preview of changes:") + else: + if _colors_enabled(): + print( + f"{Color.GREEN.value}[SUCCESS]{Color.RESET.value} Operation completed:" + ) + else: + print("[SUCCESS] Operation completed:") + + # Print consequences + for consequence in self._consequences: + print(self._format_consequence(consequence, use_result_tense=True)) + for child in consequence.children: + # Optionally filter out UNCHANGED/SKIP in results for noise reduction + # For now, show all for transparency + print(self._format_consequence(child, use_result_tense=True, indent=4)) + + def report_error(self, summary: str, details: Optional[List[str]] = None) -> None: + """Report execution failure with structured details. + + Prints error message with [ERROR] prefix in bright red color (when colors enabled). + Details are indented with 2 spaces for visual hierarchy. + + Reference: R13 Β§4.2.3 (13-error_message_formatting_v0.md) + + Args: + summary: High-level error description + details: Optional list of detail lines to print below summary + + Output format: + [ERROR] + + + + Example: + >>> reporter = ResultReporter("hatch env create") + >>> reporter.report_error( + ... "Failed to create environment 'dev'", + ... details=["Python environment creation failed: conda not available"] + ... ) + [ERROR] Failed to create environment 'dev' + Python environment creation failed: conda not available + """ + if not summary: + return + + # Print error header with color + if _colors_enabled(): + print(f"{Color.RED.value}[ERROR]{Color.RESET.value} {summary}") + else: + print(f"[ERROR] {summary}") + + # Print details with indentation + if details: + for detail in details: + print(f" {detail}") + + def report_partial_success( + self, summary: str, successes: List[str], failures: List[Tuple[str, str]] + ) -> None: + """Report mixed success/failure results with βœ“/βœ— symbols. + + Prints warning message with [WARNING] prefix in bright yellow color. + Uses βœ“/βœ— symbols for success/failure items (with ASCII fallback). + Includes summary line showing success ratio. + + Reference: R13 Β§4.2.3 (13-error_message_formatting_v0.md) + + Args: + summary: High-level summary description + successes: List of successful item descriptions + failures: List of (item, reason) tuples for failed items + + Output format: + [WARNING] + βœ“ + βœ— : + Summary: X/Y succeeded + + Example: + >>> reporter = ResultReporter("hatch mcp sync") + >>> reporter.report_partial_success( + ... "Partial synchronization", + ... successes=["claude-desktop (backup: ~/.hatch/backups/...)"], + ... failures=[("cursor", "Config file not found")] + ... ) + [WARNING] Partial synchronization + βœ“ claude-desktop (backup: ~/.hatch/backups/...) + βœ— cursor: Config file not found + Summary: 1/2 succeeded + """ + # Determine symbols based on unicode support + success_symbol = "βœ“" if _supports_unicode() else "+" + failure_symbol = "βœ—" if _supports_unicode() else "x" + + # Print warning header with color + if _colors_enabled(): + print(f"{Color.YELLOW.value}[WARNING]{Color.RESET.value} {summary}") + else: + print(f"[WARNING] {summary}") + + # Print success items + for item in successes: + if _colors_enabled(): + print( + f" {Color.GREEN.value}{success_symbol}{Color.RESET.value} {item}" + ) + else: + print(f" {success_symbol} {item}") + + # Print failure items + for item, reason in failures: + if _colors_enabled(): + print( + f" {Color.RED.value}{failure_symbol}{Color.RESET.value} {item}: {reason}" + ) + else: + print(f" {failure_symbol} {item}: {reason}") + + # Print summary line + total = len(successes) + len(failures) + succeeded = len(successes) + print(f" Summary: {succeeded}/{total} succeeded") + + +# ============================================================================= +# Error Formatting Utilities +# ============================================================================= + + +def format_validation_error(error: "ValidationError") -> None: + """Print formatted validation error with color. + + Prints error message with [ERROR] prefix in bright red color. + Optionally includes field name and suggestion if provided. + + Reference: R13 Β§4.3 (13-error_message_formatting_v0.md) + + Args: + error: ValidationError instance with message, field, and suggestion + + Output format: + [ERROR] + Field: (if provided) + Suggestion: (if provided) + + Example: + >>> from hatch.cli.cli_utils import ValidationError, format_validation_error + >>> format_validation_error(ValidationError( + ... "Invalid host 'vsc'", + ... field="--host", + ... suggestion="Supported hosts: claude-desktop, vscode, cursor" + ... )) + [ERROR] Invalid host 'vsc' + Field: --host + Suggestion: Supported hosts: claude-desktop, vscode, cursor + """ + # Print error header with color + if _colors_enabled(): + print(f"{Color.RED.value}[ERROR]{Color.RESET.value} {error.message}") + else: + print(f"[ERROR] {error.message}") + + # Print field if provided + if error.field: + print(f" Field: {error.field}") + + # Print suggestion if provided + if error.suggestion: + print(f" Suggestion: {error.suggestion}") + + +def format_info(message: str) -> None: + """Print formatted info message with color. + + Prints message with [INFO] prefix in bright blue color. + Used for informational messages like "Operation cancelled". + + Reference: R13-B Β§B.6.2 (13-error_message_formatting_appendix_b_v0.md) + + Args: + message: Info message to display + + Output format: + [INFO] + + Example: + >>> from hatch.cli.cli_utils import format_info + >>> format_info("Operation cancelled") + [INFO] Operation cancelled + """ + if _colors_enabled(): + print(f"{Color.BLUE.value}[INFO]{Color.RESET.value} {message}") + else: + print(f"[INFO] {message}") + + +def format_warning(message: str, suggestion: str = None) -> None: + """Print formatted warning message with color. + + Prints message with [WARNING] prefix in bright yellow color. + Used for non-fatal warnings that don't prevent operation completion. + + Reference: R13-A Β§A.5 P3 (13-error_message_formatting_appendix_a_v0.md) + + Args: + message: Warning message to display + suggestion: Optional suggestion for resolution + + Output format: + [WARNING] + Suggestion: (if provided) + + Example: + >>> from hatch.cli.cli_utils import format_warning + >>> format_warning("Invalid header format 'foo'", suggestion="Expected KEY=VALUE") + [WARNING] Invalid header format 'foo' + Suggestion: Expected KEY=VALUE + """ + if _colors_enabled(): + print(f"{Color.YELLOW.value}[WARNING]{Color.RESET.value} {message}") + else: + print(f"[WARNING] {message}") + + if suggestion: + print(f" Suggestion: {suggestion}") + + +# ============================================================================= +# TableFormatter Infrastructure for List Commands +# ============================================================================= + + +@dataclass +class ColumnDef: + """Column definition for TableFormatter. + + Reference: R06 Β§3.6 (06-dependency_analysis_v0.md) + Reference: R02 Β§5 (02-list_output_format_specification_v2.md) + + Attributes: + name: Column header text + width: Fixed width (int) or "auto" for auto-calculation + align: Text alignment ("left", "right", "center") + + Example: + >>> col = ColumnDef(name="Name", width=20, align="left") + >>> col_auto = ColumnDef(name="Count", width="auto", align="right") + """ + + name: str + width: Union[int, Literal["auto"]] + align: Literal["left", "right", "center"] = "left" + + +class TableFormatter: + """Aligned table output for list commands. + + Renders data as aligned columns with headers and separator line. + Supports fixed and auto-calculated column widths. + + Reference: R06 Β§3.6 (06-dependency_analysis_v0.md) + Reference: R02 Β§5 (02-list_output_format_specification_v2.md) + + Attributes: + columns: List of column definitions + + Example: + >>> columns = [ + ... ColumnDef(name="Name", width=20), + ... ColumnDef(name="Status", width=10), + ... ] + >>> formatter = TableFormatter(columns) + >>> formatter.add_row(["my-server", "active"]) + >>> print(formatter.render()) + Name Status + ───────────────────────────────── + my-server active + """ + + def __init__(self, columns: List[ColumnDef]): + """Initialize TableFormatter with column definitions. + + Args: + columns: List of ColumnDef specifying table structure + """ + self._columns = columns + self._rows: List[List[str]] = [] + + def add_row(self, values: List[str]) -> None: + """Add a data row to the table. + + Args: + values: List of string values, one per column + """ + self._rows.append(values) + + def _calculate_widths(self) -> List[int]: + """Calculate actual column widths, resolving 'auto' widths. + + Returns: + List of integer widths for each column + """ + widths = [] + for i, col in enumerate(self._columns): + if col.width == "auto": + # Calculate from header and all row values + max_width = len(col.name) + for row in self._rows: + if i < len(row): + max_width = max(max_width, len(row[i])) + widths.append(max_width) + else: + widths.append(col.width) + return widths + + def _align_value(self, value: str, width: int, align: str) -> str: + """Align a value within the specified width. + + Args: + value: The string value to align + width: Target width + align: Alignment type ("left", "right", "center") + + Returns: + Aligned string, truncated with ellipsis if too long + """ + # Truncate if too long + if len(value) > width: + if width > 1: + return value[: width - 1] + "…" + return value[:width] + + # Apply alignment + if align == "right": + return value.rjust(width) + elif align == "center": + return value.center(width) + else: # left (default) + return value.ljust(width) + + def render(self) -> str: + """Render the table as a formatted string. + + Returns: + Multi-line string with headers, separator, and data rows + """ + widths = self._calculate_widths() + lines = [] + + # Header row + header_parts = [] + for i, col in enumerate(self._columns): + header_parts.append(self._align_value(col.name, widths[i], col.align)) + lines.append(" " + " ".join(header_parts)) + + # Separator line + total_width = ( + sum(widths) + (len(widths) - 1) * 2 + 2 + ) # columns + separators + indent + lines.append(" " + "─" * (total_width - 2)) + + # Data rows + for row in self._rows: + row_parts = [] + for i, col in enumerate(self._columns): + value = row[i] if i < len(row) else "" + row_parts.append(self._align_value(value, widths[i], col.align)) + lines.append(" " + " ".join(row_parts)) + + return "\n".join(lines) + + +# Exit code constants for consistent CLI return values +EXIT_SUCCESS = 0 +EXIT_ERROR = 1 + + +def get_hatch_version() -> str: + """Get Hatch version from package metadata. + + Returns: + str: Version string from package metadata, or 'unknown (development mode)' + if package is not installed. + """ + try: + return version("hatch-xclam") + except PackageNotFoundError: + return "unknown (development mode)" + + +def request_confirmation(message: str, auto_approve: bool = False) -> bool: + """Request user confirmation with non-TTY support following Hatch patterns. + + Args: + message: The confirmation message to display + auto_approve: If True, automatically approve without prompting + + Returns: + bool: True if confirmed, False otherwise + """ + # Check for auto-approve first + if auto_approve or os.getenv("HATCH_AUTO_APPROVE", "").lower() in ( + "1", + "true", + "yes", + ): + return True + + # Interactive mode - request user input (works in both TTY and test environments) + try: + while True: + response = input(f"{message} [y/N]: ").strip().lower() + if response in ["y", "yes"]: + return True + elif response in ["n", "no", ""]: + return False + else: + print("Please enter 'y' for yes or 'n' for no.") + except (EOFError, KeyboardInterrupt): + # Only auto-approve on EOF/interrupt if not in TTY (non-interactive environment) + if not sys.stdin.isatty(): + return True + return False + + +def parse_env_vars(env_list: Optional[list]) -> dict: + """Parse environment variables from command line format. + + Args: + env_list: List of strings in KEY=VALUE format + + Returns: + dict: Dictionary of environment variable key-value pairs + """ + if not env_list: + return {} + + env_dict = {} + for env_var in env_list: + if "=" not in env_var: + format_warning( + f"Invalid environment variable format '{env_var}'", + suggestion="Expected KEY=VALUE", + ) + continue + key, value = env_var.split("=", 1) + env_dict[key.strip()] = value.strip() + + return env_dict + + +def parse_header(header_list: Optional[list]) -> dict: + """Parse HTTP headers from command line format. + + Args: + header_list: List of strings in KEY=VALUE format + + Returns: + dict: Dictionary of header key-value pairs + """ + if not header_list: + return {} + + headers_dict = {} + for header in header_list: + if "=" not in header: + format_warning( + f"Invalid header format '{header}'", suggestion="Expected KEY=VALUE" + ) + continue + key, value = header.split("=", 1) + headers_dict[key.strip()] = value.strip() + + return headers_dict + + +def parse_input(input_list: Optional[list]) -> Optional[list]: + """Parse VS Code input variable definitions from command line format. + + Format: type,id,description[,password=true] + Example: promptString,api-key,GitHub Personal Access Token,password=true + + Args: + input_list: List of input definition strings + + Returns: + List of input variable definition dictionaries, or None if no inputs provided. + """ + if not input_list: + return None + + parsed_inputs = [] + for input_str in input_list: + parts = [p.strip() for p in input_str.split(",")] + if len(parts) < 3: + format_warning( + f"Invalid input format '{input_str}'", + suggestion="Expected: type,id,description[,password=true]", + ) + continue + + input_def = {"type": parts[0], "id": parts[1], "description": parts[2]} + + # Check for optional password flag + if len(parts) > 3 and parts[3].lower() == "password=true": + input_def["password"] = True + + parsed_inputs.append(input_def) + + return parsed_inputs if parsed_inputs else None + + +def parse_host_list(host_arg: str) -> List[str]: + """Parse comma-separated host list or 'all'. + + Args: + host_arg: Comma-separated host names or 'all' for all available hosts + + Returns: + List[str]: List of host name strings + + Raises: + ValueError: If an unknown host name is provided + """ + if not host_arg: + return [] + + if host_arg.lower() == "all": + available_hosts = MCPHostRegistry.detect_available_hosts() + return [host.value for host in available_hosts] + + hosts = [] + for host_str in host_arg.split(","): + host_str = host_str.strip() + try: + host_type = MCPHostType(host_str) + hosts.append(host_type.value) + except ValueError: + available = [h.value for h in MCPHostType] + raise ValueError(f"Unknown host '{host_str}'. Available: {available}") + + return hosts + + +def get_package_mcp_server_config( + env_manager: HatchEnvironmentManager, env_name: str, package_name: str +) -> MCPServerConfig: + """Get MCP server configuration for a package using existing APIs. + + Args: + env_manager: The environment manager instance + env_name: Name of the environment containing the package + package_name: Name of the package to get config for + + Returns: + MCPServerConfig: Server configuration for the package + + Raises: + ValueError: If package not found, not a Hatch package, or has no MCP entry point + """ + try: + # Get package info from environment + packages = env_manager.list_packages(env_name) + package_info = next( + (pkg for pkg in packages if pkg["name"] == package_name), None + ) + + if not package_info: + raise ValueError( + f"Package '{package_name}' not found in environment '{env_name}'" + ) + + # Load package metadata using existing pattern from environment_manager.py:716-727 + package_path = Path(package_info["source"]["path"]) + metadata_path = package_path / "hatch_metadata.json" + + if not metadata_path.exists(): + raise ValueError( + f"Package '{package_name}' is not a Hatch package (no hatch_metadata.json)" + ) + + with open(metadata_path, "r") as f: + metadata = json.load(f) + + # Use PackageService for schema-aware access + from hatch_validator.package.package_service import PackageService + + package_service = PackageService(metadata) + + # Get the HatchMCP entry point (this handles both v1.2.0 and v1.2.1 schemas) + mcp_entry_point = package_service.get_mcp_entry_point() + if not mcp_entry_point: + raise ValueError( + f"Package '{package_name}' does not have a HatchMCP entry point" + ) + + # Get environment-specific Python executable + python_executable = env_manager.get_current_python_executable() + if not python_executable: + # Fallback to system Python if no environment-specific Python available + python_executable = "python" + + # Create server configuration + server_path = str(package_path / mcp_entry_point) + server_config = MCPServerConfig( + name=package_name, command=python_executable, args=[server_path], env={} + ) + + return server_config + + except Exception as e: + raise ValueError( + f"Failed to get MCP server config for package '{package_name}': {e}" + ) diff --git a/hatch/cli_hatch.py b/hatch/cli_hatch.py index 4747206..79a6f66 100644 --- a/hatch/cli_hatch.py +++ b/hatch/cli_hatch.py @@ -1,24 +1,101 @@ -"""Command-line interface for the Hatch package manager. - -This module provides the CLI functionality for Hatch, allowing users to: -- Create new package templates -- Validate packages -- Manage environments -- Manage packages within environments +"""Backward compatibility shim for Hatch CLI. + +.. deprecated:: 0.7.2 + This module is deprecated. Import from ``hatch.cli`` instead. + This shim will be removed in version 0.9.0. + +This module re-exports all public symbols from the new hatch.cli package +to maintain backward compatibility for external consumers who import from +hatch.cli_hatch directly. + +Migration Note: + New code should import from hatch.cli instead: + + # Old (deprecated): + from hatch.cli_hatch import main, handle_mcp_configure + + # New (preferred): + from hatch.cli import main + from hatch.cli.cli_mcp import handle_mcp_configure + +Implementation Modules: + - hatch.cli.__main__: Entry point and argument parsing + - hatch.cli.cli_utils: Shared utilities and constants + - hatch.cli.cli_mcp: MCP host configuration handlers + - hatch.cli.cli_env: Environment management handlers + - hatch.cli.cli_package: Package management handlers + - hatch.cli.cli_system: System commands (create, validate) + +Exported Symbols: + - main: CLI entry point + - All MCP handlers (handle_mcp_*) + - All utility functions (parse_*, request_confirmation, etc.) + - Exit code constants (EXIT_SUCCESS, EXIT_ERROR) + - HatchEnvironmentManager (re-exported for convenience) """ -import argparse -import json -import logging -import shlex -import sys -from importlib.metadata import PackageNotFoundError, version -from pathlib import Path -from typing import List, Optional +# Re-export main entry point +from hatch.cli import main + +# Re-export utilities +from hatch.cli.cli_utils import ( + EXIT_SUCCESS, + EXIT_ERROR, + get_hatch_version, + request_confirmation, + parse_env_vars, + parse_header, + parse_input, + parse_host_list, + get_package_mcp_server_config, +) + +# Re-export MCP handlers (for backward compatibility with tests) +from hatch.cli.cli_mcp import ( + handle_mcp_discover_hosts, + handle_mcp_discover_servers, + handle_mcp_list_hosts, + handle_mcp_list_servers, + handle_mcp_backup_restore, + handle_mcp_backup_list, + handle_mcp_backup_clean, + handle_mcp_configure, + handle_mcp_remove, + handle_mcp_remove_server, + handle_mcp_remove_host, + handle_mcp_sync, +) + +# Re-export environment handlers +from hatch.cli.cli_env import ( + handle_env_create, + handle_env_remove, + handle_env_list, + handle_env_use, + handle_env_current, + handle_env_show, + handle_env_python_init, + handle_env_python_info, + handle_env_python_remove, + handle_env_python_shell, + handle_env_python_add_hatch_mcp, +) + +# Re-export package handlers +from hatch.cli.cli_package import ( + handle_package_add, + handle_package_remove, + handle_package_list, + handle_package_sync, +) -from hatch_validator import HatchPackageValidator -from hatch_validator.package.package_service import PackageService +# Re-export system handlers +from hatch.cli.cli_system import ( + handle_create, + handle_validate, +) +# Re-export commonly used types for backward compatibility from hatch.environment_manager import HatchEnvironmentManager from hatch.mcp_host_config import ( MCPHostConfigurationManager, @@ -26,2825 +103,69 @@ MCPHostType, MCPServerConfig, ) -from hatch.mcp_host_config.models import HOST_MODEL_REGISTRY, MCPServerConfigOmni -from hatch.mcp_host_config.reporting import display_report, generate_conversion_report -from hatch.template_generator import create_package_template - - -def get_hatch_version() -> str: - """Get Hatch version from package metadata. - - Returns: - str: Version string from package metadata, or 'unknown (development mode)' - if package is not installed. - """ - try: - return version("hatch") - except PackageNotFoundError: - return "unknown (development mode)" - - -def parse_host_list(host_arg: str): - """Parse comma-separated host list or 'all'.""" - if not host_arg: - return [] - - if host_arg.lower() == "all": - return MCPHostRegistry.detect_available_hosts() - - hosts = [] - for host_str in host_arg.split(","): - host_str = host_str.strip() - try: - host_type = MCPHostType(host_str) - hosts.append(host_type) - except ValueError: - available = [h.value for h in MCPHostType] - raise ValueError(f"Unknown host '{host_str}'. Available: {available}") - - return hosts - - -def request_confirmation(message: str, auto_approve: bool = False) -> bool: - """Request user confirmation with non-TTY support following Hatch patterns.""" - import os - import sys - - # Check for auto-approve first - if auto_approve or os.getenv("HATCH_AUTO_APPROVE", "").lower() in ( - "1", - "true", - "yes", - ): - return True - - # Interactive mode - request user input (works in both TTY and test environments) - try: - while True: - response = input(f"{message} [y/N]: ").strip().lower() - if response in ["y", "yes"]: - return True - elif response in ["n", "no", ""]: - return False - else: - print("Please enter 'y' for yes or 'n' for no.") - except (EOFError, KeyboardInterrupt): - # Only auto-approve on EOF/interrupt if not in TTY (non-interactive environment) - if not sys.stdin.isatty(): - return True - return False - - -def get_package_mcp_server_config( - env_manager: HatchEnvironmentManager, env_name: str, package_name: str -) -> MCPServerConfig: - """Get MCP server configuration for a package using existing APIs.""" - try: - # Get package info from environment - packages = env_manager.list_packages(env_name) - package_info = next( - (pkg for pkg in packages if pkg["name"] == package_name), None - ) - - if not package_info: - raise ValueError( - f"Package '{package_name}' not found in environment '{env_name}'" - ) - - # Load package metadata using existing pattern from environment_manager.py:716-727 - package_path = Path(package_info["source"]["path"]) - metadata_path = package_path / "hatch_metadata.json" - - if not metadata_path.exists(): - raise ValueError( - f"Package '{package_name}' is not a Hatch package (no hatch_metadata.json)" - ) - - with open(metadata_path, "r") as f: - metadata = json.load(f) - - # Use PackageService for schema-aware access - from hatch_validator.package.package_service import PackageService - - package_service = PackageService(metadata) - - # Get the HatchMCP entry point (this handles both v1.2.0 and v1.2.1 schemas) - mcp_entry_point = package_service.get_mcp_entry_point() - if not mcp_entry_point: - raise ValueError( - f"Package '{package_name}' does not have a HatchMCP entry point" - ) - - # Get environment-specific Python executable - python_executable = env_manager.get_current_python_executable() - if not python_executable: - # Fallback to system Python if no environment-specific Python available - python_executable = "python" - - # Create server configuration - server_path = str(package_path / mcp_entry_point) - server_config = MCPServerConfig( - name=package_name, command=python_executable, args=[server_path], env={} - ) - - return server_config - - except Exception as e: - raise ValueError( - f"Failed to get MCP server config for package '{package_name}': {e}" - ) - - -def handle_mcp_discover_hosts(): - """Handle 'hatch mcp discover hosts' command.""" - try: - # Import strategies to trigger registration - import hatch.mcp_host_config.strategies - - available_hosts = MCPHostRegistry.detect_available_hosts() - print("Available MCP host platforms:") - - for host_type in MCPHostType: - try: - strategy = MCPHostRegistry.get_strategy(host_type) - config_path = strategy.get_config_path() - is_available = host_type in available_hosts - - status = "βœ“ Available" if is_available else "βœ— Not detected" - print(f" {host_type.value}: {status}") - if config_path: - print(f" Config path: {config_path}") - except Exception as e: - print(f" {host_type.value}: Error - {e}") - - return 0 - except Exception as e: - print(f"Error discovering hosts: {e}") - return 1 - - -def handle_mcp_discover_servers( - env_manager: HatchEnvironmentManager, env_name: Optional[str] = None -): - """Handle 'hatch mcp discover servers' command.""" - try: - env_name = env_name or env_manager.get_current_environment() - - if not env_manager.environment_exists(env_name): - print(f"Error: Environment '{env_name}' does not exist") - return 1 - - packages = env_manager.list_packages(env_name) - mcp_packages = [] - - for package in packages: - try: - # Check if package has MCP server entry point - server_config = get_package_mcp_server_config( - env_manager, env_name, package["name"] - ) - mcp_packages.append( - {"package": package, "server_config": server_config} - ) - except ValueError: - # Package doesn't have MCP server - continue - - if not mcp_packages: - print(f"No MCP servers found in environment '{env_name}'") - return 0 - - print(f"MCP servers in environment '{env_name}':") - for item in mcp_packages: - package = item["package"] - server_config = item["server_config"] - print(f" {server_config.name}:") - print( - f" Package: {package['name']} v{package.get('version', 'unknown')}" - ) - print(f" Command: {server_config.command}") - print(f" Args: {server_config.args}") - if server_config.env: - print(f" Environment: {server_config.env}") - - return 0 - except Exception as e: - print(f"Error discovering servers: {e}") - return 1 - - -def handle_mcp_list_hosts( - env_manager: HatchEnvironmentManager, - env_name: Optional[str] = None, - detailed: bool = False, -): - """Handle 'hatch mcp list hosts' command - shows configured hosts in environment.""" - try: - from collections import defaultdict - - # Resolve environment name - target_env = env_name or env_manager.get_current_environment() - - # Validate environment exists - if not env_manager.environment_exists(target_env): - available_envs = env_manager.list_environments() - print(f"Error: Environment '{target_env}' does not exist.") - if available_envs: - print(f"Available environments: {', '.join(available_envs)}") - return 1 - - # Collect hosts from configured_hosts across all packages in environment - hosts = defaultdict(int) - host_details = defaultdict(list) - - try: - env_data = env_manager.get_environment_data(target_env) - packages = env_data.get("packages", []) - - for package in packages: - package_name = package.get("name", "unknown") - configured_hosts = package.get("configured_hosts", {}) - - for host_name, host_config in configured_hosts.items(): - hosts[host_name] += 1 - if detailed: - config_path = host_config.get("config_path", "N/A") - configured_at = host_config.get("configured_at", "N/A") - host_details[host_name].append( - { - "package": package_name, - "config_path": config_path, - "configured_at": configured_at, - } - ) - - except Exception as e: - print(f"Error reading environment data: {e}") - return 1 - - # Display results - if not hosts: - print(f"No configured hosts for environment '{target_env}'") - return 0 - - print(f"Configured hosts for environment '{target_env}':") - - for host_name, package_count in sorted(hosts.items()): - if detailed: - print(f"\n{host_name} ({package_count} packages):") - for detail in host_details[host_name]: - print(f" - Package: {detail['package']}") - print(f" Config path: {detail['config_path']}") - print(f" Configured at: {detail['configured_at']}") - else: - print(f" - {host_name} ({package_count} packages)") - - return 0 - except Exception as e: - print(f"Error listing hosts: {e}") - return 1 - - -def handle_mcp_list_servers( - env_manager: HatchEnvironmentManager, env_name: Optional[str] = None -): - """Handle 'hatch mcp list servers' command.""" - try: - env_name = env_name or env_manager.get_current_environment() - - if not env_manager.environment_exists(env_name): - print(f"Error: Environment '{env_name}' does not exist") - return 1 - - packages = env_manager.list_packages(env_name) - mcp_packages = [] - - for package in packages: - # Check if package has host configuration tracking (indicating MCP server) - configured_hosts = package.get("configured_hosts", {}) - if configured_hosts: - # Use the tracked server configuration from any host - first_host = next(iter(configured_hosts.values())) - server_config_data = first_host.get("server_config", {}) - - # Create a simple server config object - class SimpleServerConfig: - def __init__(self, data): - self.name = data.get("name", package["name"]) - self.command = data.get("command", "unknown") - self.args = data.get("args", []) - - server_config = SimpleServerConfig(server_config_data) - mcp_packages.append( - {"package": package, "server_config": server_config} - ) - else: - # Try the original method as fallback - try: - server_config = get_package_mcp_server_config( - env_manager, env_name, package["name"] - ) - mcp_packages.append( - {"package": package, "server_config": server_config} - ) - except: - # Package doesn't have MCP server or method failed - continue - - if not mcp_packages: - print(f"No MCP servers configured in environment '{env_name}'") - return 0 - - print(f"MCP servers in environment '{env_name}':") - print(f"{'Server Name':<20} {'Package':<20} {'Version':<10} {'Command'}") - print("-" * 80) - - for item in mcp_packages: - package = item["package"] - server_config = item["server_config"] - - server_name = server_config.name - package_name = package["name"] - version = package.get("version", "unknown") - command = f"{server_config.command} {' '.join(server_config.args)}" - - print(f"{server_name:<20} {package_name:<20} {version:<10} {command}") - - # Display host configuration tracking information - configured_hosts = package.get("configured_hosts", {}) - if configured_hosts: - print(f"{'':>20} Configured on hosts:") - for hostname, host_config in configured_hosts.items(): - config_path = host_config.get("config_path", "unknown") - last_synced = host_config.get("last_synced", "unknown") - # Format the timestamp for better readability - if last_synced != "unknown": - try: - from datetime import datetime - - dt = datetime.fromisoformat( - last_synced.replace("Z", "+00:00") - ) - last_synced = dt.strftime("%Y-%m-%d %H:%M:%S") - except: - pass # Keep original format if parsing fails - print( - f"{'':>22} - {hostname}: {config_path} (synced: {last_synced})" - ) - else: - print(f"{'':>20} No host configurations tracked") - print() # Add blank line between servers - - return 0 - except Exception as e: - print(f"Error listing servers: {e}") - return 1 - - -def handle_mcp_backup_restore( - env_manager: HatchEnvironmentManager, - host: str, - backup_file: Optional[str] = None, - dry_run: bool = False, - auto_approve: bool = False, -): - """Handle 'hatch mcp backup restore' command.""" - try: - from hatch.mcp_host_config.backup import MCPHostConfigBackupManager - - # Validate host type - try: - host_type = MCPHostType(host) - except ValueError: - print( - f"Error: Invalid host '{host}'. Supported hosts: {[h.value for h in MCPHostType]}" - ) - return 1 - - backup_manager = MCPHostConfigBackupManager() - - # Get backup file path - if backup_file: - backup_path = backup_manager.backup_root / host / backup_file - if not backup_path.exists(): - print(f"Error: Backup file '{backup_file}' not found for host '{host}'") - return 1 - else: - backup_path = backup_manager._get_latest_backup(host) - if not backup_path: - print(f"Error: No backups found for host '{host}'") - return 1 - backup_file = backup_path.name - - if dry_run: - print(f"[DRY RUN] Would restore backup for host '{host}':") - print(f"[DRY RUN] Backup file: {backup_file}") - print(f"[DRY RUN] Backup path: {backup_path}") - return 0 - - # Confirm operation unless auto-approved - if not request_confirmation( - f"Restore backup '{backup_file}' for host '{host}'? This will overwrite current configuration.", - auto_approve, - ): - print("Operation cancelled.") - return 0 - - # Perform restoration - success = backup_manager.restore_backup(host, backup_file) - - if success: - print( - f"[SUCCESS] Successfully restored backup '{backup_file}' for host '{host}'" - ) - - # Read restored configuration to get actual server list - try: - # Import strategies to trigger registration - import hatch.mcp_host_config.strategies - - host_type = MCPHostType(host) - strategy = MCPHostRegistry.get_strategy(host_type) - restored_config = strategy.read_configuration() - - # Update environment tracking to match restored state - updates_count = ( - env_manager.apply_restored_host_configuration_to_environments( - host, restored_config.servers - ) - ) - if updates_count > 0: - print( - f"Synchronized {updates_count} package entries with restored configuration" - ) - - except Exception as e: - print(f"Warning: Could not synchronize environment tracking: {e}") - - return 0 - else: - print(f"[ERROR] Failed to restore backup '{backup_file}' for host '{host}'") - return 1 - - except Exception as e: - print(f"Error restoring backup: {e}") - return 1 - - -def handle_mcp_backup_list(host: str, detailed: bool = False): - """Handle 'hatch mcp backup list' command.""" - try: - from hatch.mcp_host_config.backup import MCPHostConfigBackupManager - - # Validate host type - try: - host_type = MCPHostType(host) - except ValueError: - print( - f"Error: Invalid host '{host}'. Supported hosts: {[h.value for h in MCPHostType]}" - ) - return 1 - - backup_manager = MCPHostConfigBackupManager() - backups = backup_manager.list_backups(host) - - if not backups: - print(f"No backups found for host '{host}'") - return 0 - - print(f"Backups for host '{host}' ({len(backups)} found):") - - if detailed: - print(f"{'Backup File':<40} {'Created':<20} {'Size':<10} {'Age (days)'}") - print("-" * 80) - - for backup in backups: - created = backup.timestamp.strftime("%Y-%m-%d %H:%M:%S") - size = f"{backup.file_size:,} B" - age = backup.age_days - - print(f"{backup.file_path.name:<40} {created:<20} {size:<10} {age}") - else: - for backup in backups: - created = backup.timestamp.strftime("%Y-%m-%d %H:%M:%S") - print( - f" {backup.file_path.name} (created: {created}, {backup.age_days} days ago)" - ) - - return 0 - except Exception as e: - print(f"Error listing backups: {e}") - return 1 - - -def handle_mcp_backup_clean( - host: str, - older_than_days: Optional[int] = None, - keep_count: Optional[int] = None, - dry_run: bool = False, - auto_approve: bool = False, -): - """Handle 'hatch mcp backup clean' command.""" - try: - from hatch.mcp_host_config.backup import MCPHostConfigBackupManager - - # Validate host type - try: - host_type = MCPHostType(host) - except ValueError: - print( - f"Error: Invalid host '{host}'. Supported hosts: {[h.value for h in MCPHostType]}" - ) - return 1 - - # Validate cleanup criteria - if not older_than_days and not keep_count: - print("Error: Must specify either --older-than-days or --keep-count") - return 1 - - backup_manager = MCPHostConfigBackupManager() - backups = backup_manager.list_backups(host) - - if not backups: - print(f"No backups found for host '{host}'") - return 0 - - # Determine which backups would be cleaned - to_clean = [] - - if older_than_days: - for backup in backups: - if backup.age_days > older_than_days: - to_clean.append(backup) - - if keep_count and len(backups) > keep_count: - # Keep newest backups, remove oldest - to_clean.extend(backups[keep_count:]) - - # Remove duplicates while preserving order - seen = set() - unique_to_clean = [] - for backup in to_clean: - if backup.file_path not in seen: - seen.add(backup.file_path) - unique_to_clean.append(backup) - - if not unique_to_clean: - print(f"No backups match cleanup criteria for host '{host}'") - return 0 - - if dry_run: - print( - f"[DRY RUN] Would clean {len(unique_to_clean)} backup(s) for host '{host}':" - ) - for backup in unique_to_clean: - print( - f"[DRY RUN] {backup.file_path.name} (age: {backup.age_days} days)" - ) - return 0 - - # Confirm operation unless auto-approved - if not request_confirmation( - f"Clean {len(unique_to_clean)} backup(s) for host '{host}'?", auto_approve - ): - print("Operation cancelled.") - return 0 - - # Perform cleanup - filters = {} - if older_than_days: - filters["older_than_days"] = older_than_days - if keep_count: - filters["keep_count"] = keep_count - - cleaned_count = backup_manager.clean_backups(host, **filters) - - if cleaned_count > 0: - print(f"βœ“ Successfully cleaned {cleaned_count} backup(s) for host '{host}'") - return 0 - else: - print(f"No backups were cleaned for host '{host}'") - return 0 - - except Exception as e: - print(f"Error cleaning backups: {e}") - return 1 - - -def parse_env_vars(env_list: Optional[list]) -> dict: - """Parse environment variables from command line format.""" - if not env_list: - return {} - - env_dict = {} - for env_var in env_list: - if "=" not in env_var: - print( - f"Warning: Invalid environment variable format '{env_var}'. Expected KEY=VALUE" - ) - continue - key, value = env_var.split("=", 1) - env_dict[key.strip()] = value.strip() - - return env_dict - - -def parse_header(header_list: Optional[list]) -> dict: - """Parse HTTP headers from command line format.""" - if not header_list: - return {} - - headers_dict = {} - for header in header_list: - if "=" not in header: - print(f"Warning: Invalid header format '{header}'. Expected KEY=VALUE") - continue - key, value = header.split("=", 1) - headers_dict[key.strip()] = value.strip() - - return headers_dict - - -def parse_input(input_list: Optional[list]) -> Optional[list]: - """Parse VS Code input variable definitions from command line format. - - Format: type,id,description[,password=true] - Example: promptString,api-key,GitHub Personal Access Token,password=true - - Returns: - List of input variable definition dictionaries, or None if no inputs provided. - """ - if not input_list: - return None - - parsed_inputs = [] - for input_str in input_list: - parts = [p.strip() for p in input_str.split(",")] - if len(parts) < 3: - print( - f"Warning: Invalid input format '{input_str}'. Expected: type,id,description[,password=true]" - ) - continue - - input_def = {"type": parts[0], "id": parts[1], "description": parts[2]} - - # Check for optional password flag - if len(parts) > 3 and parts[3].lower() == "password=true": - input_def["password"] = True - - parsed_inputs.append(input_def) - - return parsed_inputs if parsed_inputs else None - - -def handle_mcp_configure( - host: str, - server_name: str, - command: str, - args: list, - env: Optional[list] = None, - url: Optional[str] = None, - header: Optional[list] = None, - timeout: Optional[int] = None, - trust: bool = False, - cwd: Optional[str] = None, - env_file: Optional[str] = None, - http_url: Optional[str] = None, - include_tools: Optional[list] = None, - exclude_tools: Optional[list] = None, - input: Optional[list] = None, - disabled: Optional[bool] = None, - auto_approve_tools: Optional[list] = None, - disable_tools: Optional[list] = None, - env_vars: Optional[list] = None, - startup_timeout: Optional[int] = None, - tool_timeout: Optional[int] = None, - enabled: Optional[bool] = None, - bearer_token_env_var: Optional[str] = None, - env_header: Optional[list] = None, - no_backup: bool = False, - dry_run: bool = False, - auto_approve: bool = False, -): - """Handle 'hatch mcp configure' command with ALL host-specific arguments. - - Host-specific arguments are accepted for all hosts. The reporting system will - show unsupported fields as "UNSUPPORTED" in the conversion report rather than - rejecting them upfront. - """ - try: - # Validate host type - try: - host_type = MCPHostType(host) - except ValueError: - print( - f"Error: Invalid host '{host}'. Supported hosts: {[h.value for h in MCPHostType]}" - ) - return 1 - - # Validate Claude Desktop/Code transport restrictions (Issue 2) - if host_type in (MCPHostType.CLAUDE_DESKTOP, MCPHostType.CLAUDE_CODE): - if url is not None: - print( - f"Error: {host} does not support remote servers (--url). Only local servers with --command are supported." - ) - return 1 - - # Validate argument dependencies - if command and header: - print( - "Error: --header can only be used with --url or --http-url (remote servers), not with --command (local servers)" - ) - return 1 - - if (url or http_url) and args: - print( - "Error: --args can only be used with --command (local servers), not with --url or --http-url (remote servers)" - ) - return 1 - - # NOTE: We do NOT validate host-specific arguments here. - # The reporting system will show unsupported fields as "UNSUPPORTED" in the conversion report. - # This allows users to see which fields are not supported by their target host without blocking the operation. - - # Check if server exists (for partial update support) - manager = MCPHostConfigurationManager() - existing_config = manager.get_server_config(host, server_name) - is_update = existing_config is not None - - # Conditional validation: Create requires command OR url OR http_url, update does not - if not is_update: - # Create operation: require command, url, or http_url - if not command and not url and not http_url: - print( - f"Error: When creating a new server, you must provide either --command (for local servers), --url (for SSE remote servers), or --http-url (for HTTP remote servers, Gemini only)" - ) - return 1 - - # Parse environment variables, headers, and inputs - env_dict = parse_env_vars(env) - headers_dict = parse_header(header) - inputs_list = parse_input(input) - - # Create Omni configuration (universal model) - # Only include fields that have actual values to ensure model_dump(exclude_unset=True) works correctly - omni_config_data = {"name": server_name} - - if command is not None: - omni_config_data["command"] = command - if args is not None: - # Process args with shlex.split() to handle quoted strings (Issue 4) - processed_args = [] - for arg in args: - if arg: # Skip empty strings - try: - # Split quoted strings into individual arguments - split_args = shlex.split(arg) - processed_args.extend(split_args) - except ValueError as e: - # Handle invalid quotes gracefully - print(f"Warning: Invalid quote in argument '{arg}': {e}") - processed_args.append(arg) - omni_config_data["args"] = processed_args if processed_args else None - if env_dict: - omni_config_data["env"] = env_dict - if url is not None: - omni_config_data["url"] = url - if headers_dict: - omni_config_data["headers"] = headers_dict - - # Host-specific fields (Gemini) - if timeout is not None: - omni_config_data["timeout"] = timeout - if trust: - omni_config_data["trust"] = trust - if cwd is not None: - omni_config_data["cwd"] = cwd - if http_url is not None: - omni_config_data["httpUrl"] = http_url - if include_tools is not None: - omni_config_data["includeTools"] = include_tools - if exclude_tools is not None: - omni_config_data["excludeTools"] = exclude_tools - - # Host-specific fields (Cursor/VS Code/LM Studio) - if env_file is not None: - omni_config_data["envFile"] = env_file - - # Host-specific fields (VS Code) - if inputs_list is not None: - omni_config_data["inputs"] = inputs_list - - # Host-specific fields (Kiro) - if disabled is not None: - omni_config_data["disabled"] = disabled - if auto_approve_tools is not None: - omni_config_data["autoApprove"] = auto_approve_tools - if disable_tools is not None: - omni_config_data["disabledTools"] = disable_tools - - # Host-specific fields (Codex) - if env_vars is not None: - omni_config_data["env_vars"] = env_vars - if startup_timeout is not None: - omni_config_data["startup_timeout_sec"] = startup_timeout - if tool_timeout is not None: - omni_config_data["tool_timeout_sec"] = tool_timeout - if enabled is not None: - omni_config_data["enabled"] = enabled - if bearer_token_env_var is not None: - omni_config_data["bearer_token_env_var"] = bearer_token_env_var - if env_header is not None: - # Parse KEY=ENV_VAR_NAME format into dict - env_http_headers = {} - for header_spec in env_header: - if '=' in header_spec: - key, env_var_name = header_spec.split('=', 1) - env_http_headers[key] = env_var_name - if env_http_headers: - omni_config_data["env_http_headers"] = env_http_headers - - # Partial update merge logic - if is_update: - # Merge with existing configuration - existing_data = existing_config.model_dump( - exclude_unset=True, exclude={"name"} - ) - - # Handle command/URL/httpUrl switching behavior - # If switching from command to URL or httpUrl: clear command-based fields - if ( - url is not None or http_url is not None - ) and existing_config.command is not None: - existing_data.pop("command", None) - existing_data.pop("args", None) - existing_data.pop( - "type", None - ) # Clear type field when switching transports (Issue 1) - - # If switching from URL/httpUrl to command: clear URL-based fields - if command is not None and ( - existing_config.url is not None - or getattr(existing_config, "httpUrl", None) is not None - ): - existing_data.pop("url", None) - existing_data.pop("httpUrl", None) - existing_data.pop("headers", None) - existing_data.pop( - "type", None - ) # Clear type field when switching transports (Issue 1) - - # Merge: new values override existing values - merged_data = {**existing_data, **omni_config_data} - omni_config_data = merged_data - - # Create Omni model - omni_config = MCPServerConfigOmni(**omni_config_data) - - # Convert to host-specific model using HOST_MODEL_REGISTRY - host_model_class = HOST_MODEL_REGISTRY.get(host_type) - if not host_model_class: - print(f"Error: No model registered for host '{host}'") - return 1 - - # Convert Omni to host-specific model - server_config = host_model_class.from_omni(omni_config) - - # Generate conversion report - report = generate_conversion_report( - operation="update" if is_update else "create", - server_name=server_name, - target_host=host_type, - omni=omni_config, - old_config=existing_config if is_update else None, - dry_run=dry_run, - ) - - # Display conversion report - if dry_run: - print( - f"[DRY RUN] Would configure MCP server '{server_name}' on host '{host}':" - ) - print(f"[DRY RUN] Command: {command}") - if args: - print(f"[DRY RUN] Args: {args}") - if env_dict: - print(f"[DRY RUN] Environment: {env_dict}") - if url: - print(f"[DRY RUN] URL: {url}") - if headers_dict: - print(f"[DRY RUN] Headers: {headers_dict}") - print(f"[DRY RUN] Backup: {'Disabled' if no_backup else 'Enabled'}") - # Display report in dry-run mode - display_report(report) - return 0 - - # Display report before confirmation - display_report(report) - - # Confirm operation unless auto-approved - if not request_confirmation( - f"Configure MCP server '{server_name}' on host '{host}'?", auto_approve - ): - print("Operation cancelled.") - return 0 - - # Perform configuration - mcp_manager = MCPHostConfigurationManager() - result = mcp_manager.configure_server( - server_config=server_config, hostname=host, no_backup=no_backup - ) - - if result.success: - print( - f"[SUCCESS] Successfully configured MCP server '{server_name}' on host '{host}'" - ) - if result.backup_path: - print(f" Backup created: {result.backup_path}") - return 0 - else: - print( - f"[ERROR] Failed to configure MCP server '{server_name}' on host '{host}': {result.error_message}" - ) - return 1 - - except Exception as e: - print(f"Error configuring MCP server: {e}") - return 1 - - -def handle_mcp_remove( - host: str, - server_name: str, - no_backup: bool = False, - dry_run: bool = False, - auto_approve: bool = False, -): - """Handle 'hatch mcp remove' command.""" - try: - # Validate host type - try: - host_type = MCPHostType(host) - except ValueError: - print( - f"Error: Invalid host '{host}'. Supported hosts: {[h.value for h in MCPHostType]}" - ) - return 1 - - if dry_run: - print( - f"[DRY RUN] Would remove MCP server '{server_name}' from host '{host}'" - ) - print(f"[DRY RUN] Backup: {'Disabled' if no_backup else 'Enabled'}") - return 0 - - # Confirm operation unless auto-approved - if not request_confirmation( - f"Remove MCP server '{server_name}' from host '{host}'?", auto_approve - ): - print("Operation cancelled.") - return 0 - - # Perform removal - mcp_manager = MCPHostConfigurationManager() - result = mcp_manager.remove_server( - server_name=server_name, hostname=host, no_backup=no_backup - ) - - if result.success: - print( - f"[SUCCESS] Successfully removed MCP server '{server_name}' from host '{host}'" - ) - if result.backup_path: - print(f" Backup created: {result.backup_path}") - return 0 - else: - print( - f"[ERROR] Failed to remove MCP server '{server_name}' from host '{host}': {result.error_message}" - ) - return 1 - - except Exception as e: - print(f"Error removing MCP server: {e}") - return 1 - - -def parse_host_list(host_arg: str) -> List[str]: - """Parse comma-separated host list or 'all'.""" - if not host_arg: - return [] - - if host_arg.lower() == "all": - from hatch.mcp_host_config.host_management import MCPHostRegistry - - available_hosts = MCPHostRegistry.detect_available_hosts() - return [host.value for host in available_hosts] - - hosts = [] - for host_str in host_arg.split(","): - host_str = host_str.strip() - try: - host_type = MCPHostType(host_str) - hosts.append(host_type.value) - except ValueError: - available = [h.value for h in MCPHostType] - raise ValueError(f"Unknown host '{host_str}'. Available: {available}") - - return hosts - - -def handle_mcp_remove_server( - env_manager: HatchEnvironmentManager, - server_name: str, - hosts: Optional[str] = None, - env: Optional[str] = None, - no_backup: bool = False, - dry_run: bool = False, - auto_approve: bool = False, -): - """Handle 'hatch mcp remove server' command.""" - try: - # Determine target hosts - if hosts: - target_hosts = parse_host_list(hosts) - elif env: - # TODO: Implement environment-based server removal - print("Error: Environment-based removal not yet implemented") - return 1 - else: - print("Error: Must specify either --host or --env") - return 1 - - if not target_hosts: - print("Error: No valid hosts specified") - return 1 - - if dry_run: - print( - f"[DRY RUN] Would remove MCP server '{server_name}' from hosts: {', '.join(target_hosts)}" - ) - print(f"[DRY RUN] Backup: {'Disabled' if no_backup else 'Enabled'}") - return 0 - - # Confirm operation unless auto-approved - hosts_str = ", ".join(target_hosts) - if not request_confirmation( - f"Remove MCP server '{server_name}' from hosts: {hosts_str}?", auto_approve - ): - print("Operation cancelled.") - return 0 - - # Perform removal on each host - mcp_manager = MCPHostConfigurationManager() - success_count = 0 - total_count = len(target_hosts) - - for host in target_hosts: - result = mcp_manager.remove_server( - server_name=server_name, hostname=host, no_backup=no_backup - ) - - if result.success: - print(f"[SUCCESS] Successfully removed '{server_name}' from '{host}'") - if result.backup_path: - print(f" Backup created: {result.backup_path}") - success_count += 1 - - # Update environment tracking for current environment only - current_env = env_manager.get_current_environment() - if current_env: - env_manager.remove_package_host_configuration( - current_env, server_name, host - ) - else: - print( - f"[ERROR] Failed to remove '{server_name}' from '{host}': {result.error_message}" - ) - - # Summary - if success_count == total_count: - print(f"[SUCCESS] Removed '{server_name}' from all {total_count} hosts") - return 0 - elif success_count > 0: - print( - f"[PARTIAL SUCCESS] Removed '{server_name}' from {success_count}/{total_count} hosts" - ) - return 1 - else: - print(f"[ERROR] Failed to remove '{server_name}' from any hosts") - return 1 - except Exception as e: - print(f"Error removing MCP server: {e}") - return 1 - - -def handle_mcp_remove_host( - env_manager: HatchEnvironmentManager, - host_name: str, - no_backup: bool = False, - dry_run: bool = False, - auto_approve: bool = False, -): - """Handle 'hatch mcp remove host' command.""" - try: - # Validate host type - try: - host_type = MCPHostType(host_name) - except ValueError: - print( - f"Error: Invalid host '{host_name}'. Supported hosts: {[h.value for h in MCPHostType]}" - ) - return 1 - - if dry_run: - print(f"[DRY RUN] Would remove entire host configuration for '{host_name}'") - print(f"[DRY RUN] Backup: {'Disabled' if no_backup else 'Enabled'}") - return 0 - - # Confirm operation unless auto-approved - if not request_confirmation( - f"Remove entire host configuration for '{host_name}'? This will remove ALL MCP servers from this host.", - auto_approve, - ): - print("Operation cancelled.") - return 0 - - # Perform host configuration removal - mcp_manager = MCPHostConfigurationManager() - result = mcp_manager.remove_host_configuration( - hostname=host_name, no_backup=no_backup - ) - - if result.success: - print( - f"[SUCCESS] Successfully removed host configuration for '{host_name}'" - ) - if result.backup_path: - print(f" Backup created: {result.backup_path}") - - # Update environment tracking across all environments - updates_count = env_manager.clear_host_from_all_packages_all_envs(host_name) - if updates_count > 0: - print(f"Updated {updates_count} package entries across environments") - - return 0 - else: - print( - f"[ERROR] Failed to remove host configuration for '{host_name}': {result.error_message}" - ) - return 1 - - except Exception as e: - print(f"Error removing host configuration: {e}") - return 1 - - -def handle_mcp_sync( - from_env: Optional[str] = None, - from_host: Optional[str] = None, - to_hosts: Optional[str] = None, - servers: Optional[str] = None, - pattern: Optional[str] = None, - dry_run: bool = False, - auto_approve: bool = False, - no_backup: bool = False, -) -> int: - """Handle 'hatch mcp sync' command.""" - try: - # Parse target hosts - if not to_hosts: - print("Error: Must specify --to-host") - return 1 - - target_hosts = parse_host_list(to_hosts) - - # Parse server filters - server_list = None - if servers: - server_list = [s.strip() for s in servers.split(",") if s.strip()] - - if dry_run: - source_desc = ( - f"environment '{from_env}'" if from_env else f"host '{from_host}'" - ) - target_desc = f"hosts: {', '.join(target_hosts)}" - print(f"[DRY RUN] Would synchronize from {source_desc} to {target_desc}") - - if server_list: - print(f"[DRY RUN] Server filter: {', '.join(server_list)}") - elif pattern: - print(f"[DRY RUN] Pattern filter: {pattern}") - - print(f"[DRY RUN] Backup: {'Disabled' if no_backup else 'Enabled'}") - return 0 - - # Confirm operation unless auto-approved - source_desc = f"environment '{from_env}'" if from_env else f"host '{from_host}'" - target_desc = f"{len(target_hosts)} host(s)" - if not request_confirmation( - f"Synchronize MCP configurations from {source_desc} to {target_desc}?", - auto_approve, - ): - print("Operation cancelled.") - return 0 - - # Perform synchronization - mcp_manager = MCPHostConfigurationManager() - result = mcp_manager.sync_configurations( - from_env=from_env, - from_host=from_host, - to_hosts=target_hosts, - servers=server_list, - pattern=pattern, - no_backup=no_backup, - ) - - if result.success: - print(f"[SUCCESS] Synchronization completed") - print(f" Servers synced: {result.servers_synced}") - print(f" Hosts updated: {result.hosts_updated}") - - # Show detailed results - for res in result.results: - if res.success: - backup_info = ( - f" (backup: {res.backup_path})" if res.backup_path else "" - ) - print(f" βœ“ {res.hostname}{backup_info}") - else: - print(f" βœ— {res.hostname}: {res.error_message}") - - return 0 - else: - print(f"[ERROR] Synchronization failed") - for res in result.results: - if not res.success: - print(f" βœ— {res.hostname}: {res.error_message}") - return 1 - - except ValueError as e: - print(f"Error: {e}") - return 1 - except Exception as e: - print(f"Error during synchronization: {e}") - return 1 - - -def main(): - """Main entry point for Hatch CLI. - - Parses command-line arguments and executes the requested commands for: - - Package template creation - - Package validation - - Environment management (create, remove, list, use, current) - - Package management (add, remove, list) - - Returns: - int: Exit code (0 for success, 1 for errors) - """ - # Configure logging - logging.basicConfig( - level=logging.INFO, - format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", - ) - - # Create argument parser - parser = argparse.ArgumentParser(description="Hatch package manager CLI") - - # Add version argument - parser.add_argument( - "--version", action="version", version=f"%(prog)s {get_hatch_version()}" - ) - - subparsers = parser.add_subparsers(dest="command", help="Command to execute") - - # Create template command - create_parser = subparsers.add_parser( - "create", help="Create a new package template" - ) - create_parser.add_argument("name", help="Package name") - create_parser.add_argument( - "--dir", "-d", default=".", help="Target directory (default: current directory)" - ) - create_parser.add_argument( - "--description", "-D", default="", help="Package description" - ) - - # Validate package command - validate_parser = subparsers.add_parser("validate", help="Validate a package") - validate_parser.add_argument("package_dir", help="Path to package directory") - - # Environment management commands - env_subparsers = subparsers.add_parser( - "env", help="Environment management commands" - ).add_subparsers(dest="env_command", help="Environment command to execute") - - # Create environment command - env_create_parser = env_subparsers.add_parser( - "create", help="Create a new environment" - ) - env_create_parser.add_argument("name", help="Environment name") - env_create_parser.add_argument( - "--description", "-D", default="", help="Environment description" - ) - env_create_parser.add_argument( - "--python-version", help="Python version for the environment (e.g., 3.11, 3.12)" - ) - env_create_parser.add_argument( - "--no-python", - action="store_true", - help="Don't create a Python environment using conda/mamba", - ) - env_create_parser.add_argument( - "--no-hatch-mcp-server", - action="store_true", - help="Don't install hatch_mcp_server wrapper in the new environment", - ) - env_create_parser.add_argument( - "--hatch_mcp_server_tag", - help="Git tag/branch reference for hatch_mcp_server wrapper installation (e.g., 'dev', 'v0.1.0')", - ) - - # Remove environment command - env_remove_parser = env_subparsers.add_parser( - "remove", help="Remove an environment" - ) - env_remove_parser.add_argument("name", help="Environment name") - - # List environments command - env_subparsers.add_parser("list", help="List all available environments") - - # Set current environment command - env_use_parser = env_subparsers.add_parser( - "use", help="Set the current environment" - ) - env_use_parser.add_argument("name", help="Environment name") - - # Show current environment command - env_subparsers.add_parser("current", help="Show the current environment") - - # Python environment management commands - advanced subcommands - env_python_subparsers = env_subparsers.add_parser( - "python", help="Manage Python environments" - ).add_subparsers( - dest="python_command", help="Python environment command to execute" - ) - - # Initialize Python environment - python_init_parser = env_python_subparsers.add_parser( - "init", help="Initialize Python environment" - ) - python_init_parser.add_argument( - "--hatch_env", - default=None, - help="Hatch environment name in which the Python environment is located (default: current environment)", - ) - python_init_parser.add_argument( - "--python-version", help="Python version (e.g., 3.11, 3.12)" - ) - python_init_parser.add_argument( - "--force", action="store_true", help="Force recreation if exists" - ) - python_init_parser.add_argument( - "--no-hatch-mcp-server", - action="store_true", - help="Don't install hatch_mcp_server wrapper in the Python environment", - ) - python_init_parser.add_argument( - "--hatch_mcp_server_tag", - help="Git tag/branch reference for hatch_mcp_server wrapper installation (e.g., 'dev', 'v0.1.0')", - ) - - # Show Python environment info - python_info_parser = env_python_subparsers.add_parser( - "info", help="Show Python environment information" - ) - python_info_parser.add_argument( - "--hatch_env", - default=None, - help="Hatch environment name in which the Python environment is located (default: current environment)", - ) - python_info_parser.add_argument( - "--detailed", action="store_true", help="Show detailed diagnostics" - ) - - # Hatch MCP server wrapper management commands - hatch_mcp_parser = env_python_subparsers.add_parser( - "add-hatch-mcp", help="Add hatch_mcp_server wrapper to the environment" - ) - ## Install MCP server command - hatch_mcp_parser.add_argument( - "--hatch_env", - default=None, - help="Hatch environment name. It must possess a valid Python environment. (default: current environment)", - ) - hatch_mcp_parser.add_argument( - "--tag", - default=None, - help="Git tag/branch reference for wrapper installation (e.g., 'dev', 'v0.1.0')", - ) - - # Remove Python environment - python_remove_parser = env_python_subparsers.add_parser( - "remove", help="Remove Python environment" - ) - python_remove_parser.add_argument( - "--hatch_env", - default=None, - help="Hatch environment name in which the Python environment is located (default: current environment)", - ) - python_remove_parser.add_argument( - "--force", action="store_true", help="Force removal without confirmation" - ) - - # Launch Python shell - python_shell_parser = env_python_subparsers.add_parser( - "shell", help="Launch Python shell in environment" - ) - python_shell_parser.add_argument( - "--hatch_env", - default=None, - help="Hatch environment name in which the Python environment is located (default: current environment)", - ) - python_shell_parser.add_argument( - "--cmd", help="Command to run in the shell (optional)" - ) - - # MCP host configuration commands - mcp_subparsers = subparsers.add_parser( - "mcp", help="MCP host configuration commands" - ).add_subparsers(dest="mcp_command", help="MCP command to execute") - - # MCP discovery commands - mcp_discover_subparsers = mcp_subparsers.add_parser( - "discover", help="Discover MCP hosts and servers" - ).add_subparsers(dest="discover_command", help="Discovery command to execute") - - # Discover hosts command - mcp_discover_hosts_parser = mcp_discover_subparsers.add_parser( - "hosts", help="Discover available MCP host platforms" - ) - - # Discover servers command - mcp_discover_servers_parser = mcp_discover_subparsers.add_parser( - "servers", help="Discover configured MCP servers" - ) - mcp_discover_servers_parser.add_argument( - "--env", - "-e", - default=None, - help="Environment name (default: current environment)", - ) - - # MCP list commands - mcp_list_subparsers = mcp_subparsers.add_parser( - "list", help="List MCP hosts and servers" - ).add_subparsers(dest="list_command", help="List command to execute") - - # List hosts command - mcp_list_hosts_parser = mcp_list_subparsers.add_parser( - "hosts", help="List configured MCP hosts from environment" - ) - mcp_list_hosts_parser.add_argument( - "--env", - "-e", - default=None, - help="Environment name (default: current environment)", - ) - mcp_list_hosts_parser.add_argument( - "--detailed", - action="store_true", - help="Show detailed host configuration information", - ) - - # List servers command - mcp_list_servers_parser = mcp_list_subparsers.add_parser( - "servers", help="List configured MCP servers from environment" - ) - mcp_list_servers_parser.add_argument( - "--env", - "-e", - default=None, - help="Environment name (default: current environment)", - ) - - # MCP backup commands - mcp_backup_subparsers = mcp_subparsers.add_parser( - "backup", help="Backup management commands" - ).add_subparsers(dest="backup_command", help="Backup command to execute") - - # Restore backup command - mcp_backup_restore_parser = mcp_backup_subparsers.add_parser( - "restore", help="Restore MCP host configuration from backup" - ) - mcp_backup_restore_parser.add_argument( - "host", help="Host platform to restore (e.g., claude-desktop, cursor)" - ) - mcp_backup_restore_parser.add_argument( - "--backup-file", - "-f", - default=None, - help="Specific backup file to restore (default: latest)", - ) - mcp_backup_restore_parser.add_argument( - "--dry-run", - action="store_true", - help="Preview restore operation without execution", - ) - mcp_backup_restore_parser.add_argument( - "--auto-approve", action="store_true", help="Skip confirmation prompts" - ) - - # List backups command - mcp_backup_list_parser = mcp_backup_subparsers.add_parser( - "list", help="List available backups for MCP host" - ) - mcp_backup_list_parser.add_argument( - "host", help="Host platform to list backups for (e.g., claude-desktop, cursor)" - ) - mcp_backup_list_parser.add_argument( - "--detailed", "-d", action="store_true", help="Show detailed backup information" - ) - - # Clean backups command - mcp_backup_clean_parser = mcp_backup_subparsers.add_parser( - "clean", help="Clean old backups based on criteria" - ) - mcp_backup_clean_parser.add_argument( - "host", help="Host platform to clean backups for (e.g., claude-desktop, cursor)" - ) - mcp_backup_clean_parser.add_argument( - "--older-than-days", type=int, help="Remove backups older than specified days" - ) - mcp_backup_clean_parser.add_argument( - "--keep-count", - type=int, - help="Keep only the specified number of newest backups", - ) - mcp_backup_clean_parser.add_argument( - "--dry-run", - action="store_true", - help="Preview cleanup operation without execution", - ) - mcp_backup_clean_parser.add_argument( - "--auto-approve", action="store_true", help="Skip confirmation prompts" - ) - - # MCP direct management commands - mcp_configure_parser = mcp_subparsers.add_parser( - "configure", help="Configure MCP server directly on host" - ) - mcp_configure_parser.add_argument( - "server_name", help="Name for the MCP server [hosts: all]" - ) - mcp_configure_parser.add_argument( - "--host", - required=True, - help="Host platform to configure (e.g., claude-desktop, cursor) [hosts: all]", - ) - - # Create mutually exclusive group for server type - server_type_group = mcp_configure_parser.add_mutually_exclusive_group() - server_type_group.add_argument( - "--command", - dest="server_command", - help="Command to execute the MCP server (for local servers) [hosts: all]", - ) - server_type_group.add_argument( - "--url", help="Server URL for remote MCP servers (SSE transport) [hosts: all except claude-desktop, claude-code]" - ) - server_type_group.add_argument( - "--http-url", help="HTTP streaming endpoint URL [hosts: gemini]" - ) - - mcp_configure_parser.add_argument( - "--args", - nargs="*", - help="Arguments for the MCP server command (only with --command) [hosts: all]", - ) - mcp_configure_parser.add_argument( - "--env-var", - action="append", - help="Environment variables (format: KEY=VALUE) [hosts: all]", - ) - mcp_configure_parser.add_argument( - "--header", - action="append", - help="HTTP headers for remote servers (format: KEY=VALUE, only with --url) [hosts: all except claude-desktop, claude-code]", - ) - - # Host-specific arguments (Gemini) - mcp_configure_parser.add_argument( - "--timeout", type=int, help="Request timeout in milliseconds [hosts: gemini]" - ) - mcp_configure_parser.add_argument( - "--trust", action="store_true", help="Bypass tool call confirmations [hosts: gemini]" - ) - mcp_configure_parser.add_argument( - "--cwd", help="Working directory for stdio transport [hosts: gemini, codex]" - ) - mcp_configure_parser.add_argument( - "--include-tools", - nargs="*", - help="Tool allowlist / enabled tools [hosts: gemini, codex]", - ) - mcp_configure_parser.add_argument( - "--exclude-tools", - nargs="*", - help="Tool blocklist / disabled tools [hosts: gemini, codex]", - ) - - # Host-specific arguments (Cursor/VS Code/LM Studio) - mcp_configure_parser.add_argument( - "--env-file", help="Path to environment file [hosts: cursor, vscode, lmstudio]" - ) - - # Host-specific arguments (VS Code) - mcp_configure_parser.add_argument( - "--input", - action="append", - help="Input variable definitions in format: type,id,description[,password=true] [hosts: vscode]", - ) - - # Host-specific arguments (Kiro) - mcp_configure_parser.add_argument( - "--disabled", - action="store_true", - default=None, - help="Disable the MCP server [hosts: kiro]" - ) - mcp_configure_parser.add_argument( - "--auto-approve-tools", - action="append", - help="Tool names to auto-approve without prompting [hosts: kiro]" - ) - mcp_configure_parser.add_argument( - "--disable-tools", - action="append", - help="Tool names to disable [hosts: kiro]" - ) - - # Codex-specific arguments - mcp_configure_parser.add_argument( - "--env-vars", - action="append", - help="Environment variable names to whitelist/forward [hosts: codex]" - ) - mcp_configure_parser.add_argument( - "--startup-timeout", - type=int, - help="Server startup timeout in seconds (default: 10) [hosts: codex]" - ) - mcp_configure_parser.add_argument( - "--tool-timeout", - type=int, - help="Tool execution timeout in seconds (default: 60) [hosts: codex]" - ) - mcp_configure_parser.add_argument( - "--enabled", - action="store_true", - default=None, - help="Enable the MCP server [hosts: codex]" - ) - mcp_configure_parser.add_argument( - "--bearer-token-env-var", - type=str, - help="Name of environment variable containing bearer token for Authorization header [hosts: codex]" - ) - mcp_configure_parser.add_argument( - "--env-header", - action="append", - help="HTTP header from environment variable in KEY=ENV_VAR_NAME format [hosts: codex]" - ) - - mcp_configure_parser.add_argument( - "--no-backup", - action="store_true", - help="Skip backup creation before configuration [hosts: all]", - ) - mcp_configure_parser.add_argument( - "--dry-run", action="store_true", help="Preview configuration without execution [hosts: all]" - ) - mcp_configure_parser.add_argument( - "--auto-approve", action="store_true", help="Skip confirmation prompts [hosts: all]" - ) - - # Remove MCP commands (object-action pattern) - mcp_remove_subparsers = mcp_subparsers.add_parser( - "remove", help="Remove MCP servers or host configurations" - ).add_subparsers(dest="remove_command", help="Remove command to execute") - - # Remove server command - mcp_remove_server_parser = mcp_remove_subparsers.add_parser( - "server", help="Remove MCP server from hosts" - ) - mcp_remove_server_parser.add_argument( - "server_name", help="Name of the MCP server to remove" - ) - mcp_remove_server_parser.add_argument( - "--host", help="Target hosts (comma-separated or 'all')" - ) - mcp_remove_server_parser.add_argument( - "--env", "-e", help="Environment name (for environment-based removal)" - ) - mcp_remove_server_parser.add_argument( - "--no-backup", action="store_true", help="Skip backup creation before removal" - ) - mcp_remove_server_parser.add_argument( - "--dry-run", action="store_true", help="Preview removal without execution" - ) - mcp_remove_server_parser.add_argument( - "--auto-approve", action="store_true", help="Skip confirmation prompts" - ) - - # Remove host command - mcp_remove_host_parser = mcp_remove_subparsers.add_parser( - "host", help="Remove entire host configuration" - ) - mcp_remove_host_parser.add_argument( - "host_name", help="Host platform to remove (e.g., claude-desktop, cursor)" - ) - mcp_remove_host_parser.add_argument( - "--no-backup", action="store_true", help="Skip backup creation before removal" - ) - mcp_remove_host_parser.add_argument( - "--dry-run", action="store_true", help="Preview removal without execution" - ) - mcp_remove_host_parser.add_argument( - "--auto-approve", action="store_true", help="Skip confirmation prompts" - ) - - # MCP synchronization command - mcp_sync_parser = mcp_subparsers.add_parser( - "sync", help="Synchronize MCP configurations between environments and hosts" - ) - - # Source options (mutually exclusive) - sync_source_group = mcp_sync_parser.add_mutually_exclusive_group(required=True) - sync_source_group.add_argument("--from-env", help="Source environment name") - sync_source_group.add_argument("--from-host", help="Source host platform") - - # Target options - mcp_sync_parser.add_argument( - "--to-host", required=True, help="Target hosts (comma-separated or 'all')" - ) - - # Filter options (mutually exclusive) - sync_filter_group = mcp_sync_parser.add_mutually_exclusive_group() - sync_filter_group.add_argument( - "--servers", help="Specific server names to sync (comma-separated)" - ) - sync_filter_group.add_argument( - "--pattern", help="Regex pattern for server selection" - ) - - # Standard options - mcp_sync_parser.add_argument( - "--dry-run", - action="store_true", - help="Preview synchronization without execution", - ) - mcp_sync_parser.add_argument( - "--auto-approve", action="store_true", help="Skip confirmation prompts" - ) - mcp_sync_parser.add_argument( - "--no-backup", - action="store_true", - help="Skip backup creation before synchronization", - ) - - # Package management commands - pkg_subparsers = subparsers.add_parser( - "package", help="Package management commands" - ).add_subparsers(dest="pkg_command", help="Package command to execute") - - # Add package command - pkg_add_parser = pkg_subparsers.add_parser( - "add", help="Add a package to the current environment" - ) - pkg_add_parser.add_argument( - "package_path_or_name", help="Path to package directory or name of the package" - ) - pkg_add_parser.add_argument( - "--env", - "-e", - default=None, - help="Environment name (default: current environment)", - ) - pkg_add_parser.add_argument( - "--version", "-v", default=None, help="Version of the package (optional)" - ) - pkg_add_parser.add_argument( - "--force-download", - "-f", - action="store_true", - help="Force download even if package is in cache", - ) - pkg_add_parser.add_argument( - "--refresh-registry", - "-r", - action="store_true", - help="Force refresh of registry data", - ) - pkg_add_parser.add_argument( - "--auto-approve", - action="store_true", - help="Automatically approve changes installation of deps for automation scenario", - ) - # MCP host configuration integration - pkg_add_parser.add_argument( - "--host", - help="Comma-separated list of MCP host platforms to configure (e.g., claude-desktop,cursor)", - ) - - # Remove package command - pkg_remove_parser = pkg_subparsers.add_parser( - "remove", help="Remove a package from the current environment" - ) - pkg_remove_parser.add_argument("package_name", help="Name of the package to remove") - pkg_remove_parser.add_argument( - "--env", - "-e", - default=None, - help="Environment name (default: current environment)", - ) - - # List packages command - pkg_list_parser = pkg_subparsers.add_parser( - "list", help="List packages in an environment" - ) - pkg_list_parser.add_argument( - "--env", "-e", help="Environment name (default: current environment)" - ) - - # Sync package MCP servers command - pkg_sync_parser = pkg_subparsers.add_parser( - "sync", help="Synchronize package MCP servers to host platforms" - ) - pkg_sync_parser.add_argument( - "package_name", help="Name of the package whose MCP servers to sync" - ) - pkg_sync_parser.add_argument( - "--host", - required=True, - help="Comma-separated list of host platforms to sync to (or 'all')", - ) - pkg_sync_parser.add_argument( - "--env", - "-e", - default=None, - help="Environment name (default: current environment)", - ) - pkg_sync_parser.add_argument( - "--dry-run", action="store_true", help="Preview changes without execution" - ) - pkg_sync_parser.add_argument( - "--auto-approve", action="store_true", help="Skip confirmation prompts" - ) - pkg_sync_parser.add_argument( - "--no-backup", action="store_true", help="Disable default backup behavior" - ) - - # General arguments for the environment manager - parser.add_argument( - "--envs-dir", - default=Path.home() / ".hatch" / "envs", - help="Directory to store environments", - ) - parser.add_argument( - "--cache-ttl", - type=int, - default=86400, - help="Cache TTL in seconds (default: 86400 seconds --> 1 day)", - ) - parser.add_argument( - "--cache-dir", - default=Path.home() / ".hatch" / "cache", - help="Directory to store cached packages", - ) - - args = parser.parse_args() - - # Initialize environment manager - env_manager = HatchEnvironmentManager( - environments_dir=args.envs_dir, - cache_ttl=args.cache_ttl, - cache_dir=args.cache_dir, - ) - - # Initialize MCP configuration manager - mcp_manager = MCPHostConfigurationManager() - - # Execute commands - if args.command == "create": - target_dir = Path(args.dir).resolve() - package_dir = create_package_template( - target_dir=target_dir, package_name=args.name, description=args.description - ) - print(f"Package template created at: {package_dir}") - - elif args.command == "validate": - package_path = Path(args.package_dir).resolve() - - # Create validator with registry data from environment manager - validator = HatchPackageValidator( - version="latest", - allow_local_dependencies=True, - registry_data=env_manager.registry_data, - ) - - # Validate the package - is_valid, validation_results = validator.validate_package(package_path) - - if is_valid: - print(f"Package validation SUCCESSFUL: {package_path}") - return 0 - else: - print(f"Package validation FAILED: {package_path}") - - # Print detailed validation results if available - if validation_results and isinstance(validation_results, dict): - for category, result in validation_results.items(): - if ( - category != "valid" - and category != "metadata" - and isinstance(result, dict) - ): - if not result.get("valid", True) and result.get("errors"): - print(f"\n{category.replace('_', ' ').title()} errors:") - for error in result["errors"]: - print(f" - {error}") - - return 1 - - elif args.command == "env": - if args.env_command == "create": - # Determine whether to create Python environment - create_python_env = not args.no_python - python_version = getattr(args, "python_version", None) - - if env_manager.create_environment( - args.name, - args.description, - python_version=python_version, - create_python_env=create_python_env, - no_hatch_mcp_server=args.no_hatch_mcp_server, - hatch_mcp_server_tag=args.hatch_mcp_server_tag, - ): - print(f"Environment created: {args.name}") - - # Show Python environment status - if create_python_env and env_manager.is_python_environment_available(): - python_exec = env_manager.python_env_manager.get_python_executable( - args.name - ) - if python_exec: - python_version_info = ( - env_manager.python_env_manager.get_python_version(args.name) - ) - print(f"Python environment: {python_exec}") - if python_version_info: - print(f"Python version: {python_version_info}") - else: - print("Python environment creation failed") - elif create_python_env: - print("Python environment requested but conda/mamba not available") - - return 0 - else: - print(f"Failed to create environment: {args.name}") - return 1 - - elif args.env_command == "remove": - if env_manager.remove_environment(args.name): - print(f"Environment removed: {args.name}") - return 0 - else: - print(f"Failed to remove environment: {args.name}") - return 1 - - elif args.env_command == "list": - environments = env_manager.list_environments() - print("Available environments:") - - # Check if conda/mamba is available for status info - conda_available = env_manager.is_python_environment_available() - - for env in environments: - current_marker = "* " if env.get("is_current") else " " - description = ( - f" - {env.get('description')}" if env.get("description") else "" - ) - - # Show basic environment info - print(f"{current_marker}{env.get('name')}{description}") - - # Show Python environment info if available - python_env = env.get("python_environment", False) - if python_env: - python_info = env_manager.get_python_environment_info( - env.get("name") - ) - if python_info: - python_version = python_info.get("python_version", "Unknown") - conda_env = python_info.get("conda_env_name", "N/A") - print(f" Python: {python_version} (conda: {conda_env})") - else: - print(f" Python: Configured but unavailable") - elif conda_available: - print(f" Python: Not configured") - else: - print(f" Python: Conda/mamba not available") - - # Show conda/mamba status - if conda_available: - manager_info = env_manager.python_env_manager.get_manager_info() - print(f"\nPython Environment Manager:") - print( - f" Conda executable: {manager_info.get('conda_executable', 'Not found')}" - ) - print( - f" Mamba executable: {manager_info.get('mamba_executable', 'Not found')}" - ) - print( - f" Preferred manager: {manager_info.get('preferred_manager', 'N/A')}" - ) - else: - print(f"\nPython Environment Manager: Conda/mamba not available") - - return 0 - - elif args.env_command == "use": - if env_manager.set_current_environment(args.name): - print(f"Current environment set to: {args.name}") - return 0 - else: - print(f"Failed to set environment: {args.name}") - return 1 - - elif args.env_command == "current": - current_env = env_manager.get_current_environment() - print(f"Current environment: {current_env}") - return 0 - - elif args.env_command == "python": - # Advanced Python environment management - if args.python_command == "init": - python_version = getattr(args, "python_version", None) - force = getattr(args, "force", False) - no_hatch_mcp_server = getattr(args, "no_hatch_mcp_server", False) - hatch_mcp_server_tag = getattr(args, "hatch_mcp_server_tag", None) - - if env_manager.create_python_environment_only( - args.hatch_env, - python_version, - force, - no_hatch_mcp_server=no_hatch_mcp_server, - hatch_mcp_server_tag=hatch_mcp_server_tag, - ): - print(f"Python environment initialized for: {args.hatch_env}") - - # Show Python environment info - python_info = env_manager.get_python_environment_info( - args.hatch_env - ) - if python_info: - print( - f" Python executable: {python_info['python_executable']}" - ) - print( - f" Python version: {python_info.get('python_version', 'Unknown')}" - ) - print( - f" Conda environment: {python_info.get('conda_env_name', 'N/A')}" - ) - - return 0 - else: - env_name = args.hatch_env or env_manager.get_current_environment() - print(f"Failed to initialize Python environment for: {env_name}") - return 1 - - elif args.python_command == "info": - detailed = getattr(args, "detailed", False) - - python_info = env_manager.get_python_environment_info(args.hatch_env) - - if python_info: - env_name = args.hatch_env or env_manager.get_current_environment() - print(f"Python environment info for '{env_name}':") - print( - f" Status: {'Active' if python_info.get('enabled', False) else 'Inactive'}" - ) - print(f" Python executable: {python_info['python_executable']}") - print( - f" Python version: {python_info.get('python_version', 'Unknown')}" - ) - print( - f" Conda environment: {python_info.get('conda_env_name', 'N/A')}" - ) - print(f" Environment path: {python_info['environment_path']}") - print(f" Created: {python_info.get('created_at', 'Unknown')}") - print(f" Package count: {python_info.get('package_count', 0)}") - print(f" Packages:") - for pkg in python_info.get("packages", []): - print(f" - {pkg['name']} ({pkg['version']})") - - if detailed: - print(f"\nDiagnostics:") - diagnostics = env_manager.get_python_environment_diagnostics( - args.hatch_env - ) - if diagnostics: - for key, value in diagnostics.items(): - print(f" {key}: {value}") - else: - print(" No diagnostics available") - - return 0 - else: - env_name = args.hatch_env or env_manager.get_current_environment() - print(f"No Python environment found for: {env_name}") - - # Show diagnostics for missing environment - if detailed: - print("\nDiagnostics:") - general_diagnostics = ( - env_manager.get_python_manager_diagnostics() - ) - for key, value in general_diagnostics.items(): - print(f" {key}: {value}") - - return 1 - - elif args.python_command == "remove": - force = getattr(args, "force", False) - - if not force: - # Ask for confirmation using TTY-aware function - env_name = args.hatch_env or env_manager.get_current_environment() - if not request_confirmation( - f"Remove Python environment for '{env_name}'?" - ): - print("Operation cancelled") - return 0 - - if env_manager.remove_python_environment_only(args.hatch_env): - env_name = args.hatch_env or env_manager.get_current_environment() - print(f"Python environment removed from: {env_name}") - return 0 - else: - env_name = args.hatch_env or env_manager.get_current_environment() - print(f"Failed to remove Python environment from: {env_name}") - return 1 - - elif args.python_command == "shell": - cmd = getattr(args, "cmd", None) - - if env_manager.launch_python_shell(args.hatch_env, cmd): - return 0 - else: - env_name = args.hatch_env or env_manager.get_current_environment() - print(f"Failed to launch Python shell for: {env_name}") - return 1 - - elif args.python_command == "add-hatch-mcp": - env_name = args.hatch_env or env_manager.get_current_environment() - tag = args.tag - - if env_manager.install_mcp_server(env_name, tag): - print( - f"hatch_mcp_server wrapper installed successfully in environment: {env_name}" - ) - return 0 - else: - print( - f"Failed to install hatch_mcp_server wrapper in environment: {env_name}" - ) - return 1 - - else: - print("Unknown Python environment command") - return 1 - - elif args.command == "package": - if args.pkg_command == "add": - # Add package to environment - if env_manager.add_package_to_environment( - args.package_path_or_name, - args.env, - args.version, - args.force_download, - args.refresh_registry, - args.auto_approve, - ): - print(f"Successfully added package: {args.package_path_or_name}") - - # Handle MCP host configuration if requested - if hasattr(args, "host") and args.host: - try: - hosts = parse_host_list(args.host) - env_name = args.env or env_manager.get_current_environment() - - package_name = args.package_path_or_name - package_service = None - - # Check if it's a local package path - pkg_path = Path(args.package_path_or_name) - if pkg_path.exists() and pkg_path.is_dir(): - # Local package - load metadata from directory - with open(pkg_path / "hatch_metadata.json", "r") as f: - metadata = json.load(f) - package_service = PackageService(metadata) - package_name = package_service.get_field("name") - else: - # Registry package - get metadata from environment manager - try: - env_data = env_manager.get_environment_data(env_name) - if env_data: - # Find the package in the environment - for pkg in env_data.packages: - if pkg.name == package_name: - # Create a minimal metadata structure for PackageService - metadata = { - "name": pkg.name, - "version": pkg.version, - "dependencies": {}, # Will be populated if needed - } - package_service = PackageService(metadata) - break - - if package_service is None: - print( - f"Warning: Could not find package '{package_name}' in environment '{env_name}'. Skipping dependency analysis." - ) - package_service = None - except Exception as e: - print( - f"Warning: Could not load package metadata for '{package_name}': {e}. Skipping dependency analysis." - ) - package_service = None - - # Get dependency names if we have package service - package_names = [] - if package_service: - # Get Hatch dependencies - dependencies = package_service.get_dependencies() - hatch_deps = dependencies.get("hatch", []) - package_names = [ - dep.get("name") for dep in hatch_deps if dep.get("name") - ] - - # Resolve local dependency paths to actual names - for i in range(len(package_names)): - dep_path = Path(package_names[i]) - if dep_path.exists() and dep_path.is_dir(): - try: - with open( - dep_path / "hatch_metadata.json", "r" - ) as f: - dep_metadata = json.load(f) - dep_service = PackageService(dep_metadata) - package_names[i] = dep_service.get_field("name") - except Exception as e: - print( - f"Warning: Could not resolve dependency path '{package_names[i]}': {e}" - ) - - # Add the main package to the list - package_names.append(package_name) - - # Get MCP server configuration for all packages - server_configs = [ - get_package_mcp_server_config( - env_manager, env_name, pkg_name - ) - for pkg_name in package_names - ] - - print( - f"Configuring MCP server for package '{package_name}' on {len(hosts)} host(s)..." - ) - - # Configure on each host - success_count = 0 - for host in hosts: # 'host', here, is a string - try: - # Convert string to MCPHostType enum - host_type = MCPHostType(host) - host_model_class = HOST_MODEL_REGISTRY.get(host_type) - if not host_model_class: - print( - f"βœ— Error: No model registered for host '{host}'" - ) - continue - - host_success_count = 0 - for i, server_config in enumerate(server_configs): - pkg_name = package_names[i] - try: - # Convert MCPServerConfig to Omni model - # Only include fields that have actual values - omni_config_data = {"name": server_config.name} - if server_config.command is not None: - omni_config_data["command"] = ( - server_config.command - ) - if server_config.args is not None: - omni_config_data["args"] = ( - server_config.args - ) - if server_config.env: - omni_config_data["env"] = server_config.env - if server_config.url is not None: - omni_config_data["url"] = server_config.url - headers = getattr( - server_config, "headers", None - ) - if headers is not None: - omni_config_data["headers"] = headers - - omni_config = MCPServerConfigOmni( - **omni_config_data - ) - - # Convert to host-specific model - host_config = host_model_class.from_omni( - omni_config - ) - - # Generate and display conversion report - report = generate_conversion_report( - operation="create", - server_name=server_config.name, - target_host=host_type, - omni=omni_config, - dry_run=False, - ) - display_report(report) - - result = mcp_manager.configure_server( - hostname=host, - server_config=host_config, - no_backup=False, # Always backup when adding packages - ) - - if result.success: - print( - f"βœ“ Configured {server_config.name} ({pkg_name}) on {host}" - ) - host_success_count += 1 - - # Update package metadata with host configuration tracking - try: - server_config_dict = { - "name": server_config.name, - "command": server_config.command, - "args": server_config.args, - } - - env_manager.update_package_host_configuration( - env_name=env_name, - package_name=pkg_name, - hostname=host, - server_config=server_config_dict, - ) - except Exception as e: - # Log but don't fail the configuration operation - print( - f"[WARNING] Failed to update package metadata for {pkg_name}: {e}" - ) - else: - print( - f"βœ— Failed to configure {server_config.name} ({pkg_name}) on {host}: {result.error_message}" - ) - - except Exception as e: - print( - f"βœ— Error configuring {server_config.name} ({pkg_name}) on {host}: {e}" - ) - - if host_success_count == len(server_configs): - success_count += 1 - - except ValueError as e: - print(f"βœ— Invalid host '{host}': {e}") - continue - - if success_count > 0: - print( - f"MCP configuration completed: {success_count}/{len(hosts)} hosts configured" - ) - else: - print("Warning: MCP configuration failed on all hosts") - - except ValueError as e: - print(f"Warning: MCP host configuration failed: {e}") - # Don't fail the entire operation for MCP configuration issues - - return 0 - else: - print(f"Failed to add package: {args.package_path_or_name}") - return 1 - - elif args.pkg_command == "remove": - if env_manager.remove_package(args.package_name, args.env): - print(f"Successfully removed package: {args.package_name}") - return 0 - else: - print(f"Failed to remove package: {args.package_name}") - return 1 - - elif args.pkg_command == "list": - packages = env_manager.list_packages(args.env) - - if not packages: - print(f"No packages found in environment: {args.env}") - return 0 - - print(f"Packages in environment '{args.env}':") - for pkg in packages: - print( - f"{pkg['name']} ({pkg['version']})\tHatch compliant: {pkg['hatch_compliant']}\tsource: {pkg['source']['uri']}\tlocation: {pkg['source']['path']}" - ) - return 0 - - elif args.pkg_command == "sync": - try: - # Parse host list - hosts = parse_host_list(args.host) - env_name = args.env or env_manager.get_current_environment() - - # Get all packages to sync (main package + dependencies) - package_names = [args.package_name] - - # Try to get dependencies for the main package - try: - env_data = env_manager.get_environment_data(env_name) - if env_data: - # Find the main package in the environment - main_package = None - for pkg in env_data.packages: - if pkg.name == args.package_name: - main_package = pkg - break - - if main_package: - # Create a minimal metadata structure for PackageService - metadata = { - "name": main_package.name, - "version": main_package.version, - "dependencies": {}, # Will be populated if needed - } - package_service = PackageService(metadata) - - # Get Hatch dependencies - dependencies = package_service.get_dependencies() - hatch_deps = dependencies.get("hatch", []) - dep_names = [ - dep.get("name") for dep in hatch_deps if dep.get("name") - ] - - # Add dependencies to the sync list (before main package) - package_names = dep_names + [args.package_name] - else: - print( - f"Warning: Package '{args.package_name}' not found in environment '{env_name}'. Syncing only the specified package." - ) - else: - print( - f"Warning: Could not access environment '{env_name}'. Syncing only the specified package." - ) - except Exception as e: - print( - f"Warning: Could not analyze dependencies for '{args.package_name}': {e}. Syncing only the specified package." - ) - - # Get MCP server configurations for all packages - server_configs = [] - for pkg_name in package_names: - try: - config = get_package_mcp_server_config( - env_manager, env_name, pkg_name - ) - server_configs.append((pkg_name, config)) - except Exception as e: - print( - f"Warning: Could not get MCP configuration for package '{pkg_name}': {e}" - ) - - if not server_configs: - print( - f"Error: No MCP server configurations found for package '{args.package_name}' or its dependencies" - ) - return 1 - - if args.dry_run: - print( - f"[DRY RUN] Would synchronize MCP servers for {len(server_configs)} package(s) to hosts: {[h for h in hosts]}" - ) - for pkg_name, config in server_configs: - print( - f"[DRY RUN] - {pkg_name}: {config.name} -> {' '.join(config.args)}" - ) - - # Generate and display conversion reports for dry-run mode - for host in hosts: - try: - host_type = MCPHostType(host) - host_model_class = HOST_MODEL_REGISTRY.get(host_type) - if not host_model_class: - print( - f"[DRY RUN] βœ— Error: No model registered for host '{host}'" - ) - continue - - # Convert to Omni model - # Only include fields that have actual values - omni_config_data = {"name": config.name} - if config.command is not None: - omni_config_data["command"] = config.command - if config.args is not None: - omni_config_data["args"] = config.args - if config.env: - omni_config_data["env"] = config.env - if config.url is not None: - omni_config_data["url"] = config.url - headers = getattr(config, "headers", None) - if headers is not None: - omni_config_data["headers"] = headers - - omni_config = MCPServerConfigOmni(**omni_config_data) - - # Generate report - report = generate_conversion_report( - operation="create", - server_name=config.name, - target_host=host_type, - omni=omni_config, - dry_run=True, - ) - print(f"[DRY RUN] Preview for {pkg_name} on {host}:") - display_report(report) - except ValueError as e: - print(f"[DRY RUN] βœ— Invalid host '{host}': {e}") - return 0 - - # Confirm operation unless auto-approved - package_desc = ( - f"package '{args.package_name}'" - if len(server_configs) == 1 - else f"{len(server_configs)} packages ('{args.package_name}' + dependencies)" - ) - if not request_confirmation( - f"Synchronize MCP servers for {package_desc} to {len(hosts)} host(s)?", - args.auto_approve, - ): - print("Operation cancelled.") - return 0 - - # Perform synchronization to each host for all packages - total_operations = len(server_configs) * len(hosts) - success_count = 0 - - for host in hosts: - try: - # Convert string to MCPHostType enum - host_type = MCPHostType(host) - host_model_class = HOST_MODEL_REGISTRY.get(host_type) - if not host_model_class: - print(f"βœ— Error: No model registered for host '{host}'") - continue - - for pkg_name, server_config in server_configs: - try: - # Convert MCPServerConfig to Omni model - # Only include fields that have actual values - omni_config_data = {"name": server_config.name} - if server_config.command is not None: - omni_config_data["command"] = server_config.command - if server_config.args is not None: - omni_config_data["args"] = server_config.args - if server_config.env: - omni_config_data["env"] = server_config.env - if server_config.url is not None: - omni_config_data["url"] = server_config.url - headers = getattr(server_config, "headers", None) - if headers is not None: - omni_config_data["headers"] = headers - - omni_config = MCPServerConfigOmni(**omni_config_data) - - # Convert to host-specific model - host_config = host_model_class.from_omni(omni_config) - - # Generate and display conversion report - report = generate_conversion_report( - operation="create", - server_name=server_config.name, - target_host=host_type, - omni=omni_config, - dry_run=False, - ) - display_report(report) - - result = mcp_manager.configure_server( - hostname=host, - server_config=host_config, - no_backup=args.no_backup, - ) - - if result.success: - print( - f"[SUCCESS] Successfully configured {server_config.name} ({pkg_name}) on {host}" - ) - success_count += 1 - - # Update package metadata with host configuration tracking - try: - server_config_dict = { - "name": server_config.name, - "command": server_config.command, - "args": server_config.args, - } - - env_manager.update_package_host_configuration( - env_name=env_name, - package_name=pkg_name, - hostname=host, - server_config=server_config_dict, - ) - except Exception as e: - # Log but don't fail the sync operation - print( - f"[WARNING] Failed to update package metadata for {pkg_name}: {e}" - ) - else: - print( - f"[ERROR] Failed to configure {server_config.name} ({pkg_name}) on {host}: {result.error_message}" - ) - - except Exception as e: - print( - f"[ERROR] Error configuring {server_config.name} ({pkg_name}) on {host}: {e}" - ) - - except ValueError as e: - print(f"βœ— Invalid host '{host}': {e}") - continue - - # Report results - if success_count == total_operations: - package_desc = ( - f"package '{args.package_name}'" - if len(server_configs) == 1 - else f"{len(server_configs)} packages" - ) - print( - f"Successfully synchronized {package_desc} to all {len(hosts)} host(s)" - ) - return 0 - elif success_count > 0: - print( - f"Partially synchronized: {success_count}/{total_operations} operations succeeded" - ) - return 1 - else: - package_desc = ( - f"package '{args.package_name}'" - if len(server_configs) == 1 - else f"{len(server_configs)} packages" - ) - print(f"Failed to synchronize {package_desc} to any hosts") - return 1 - - except ValueError as e: - print(f"Error: {e}") - return 1 - - else: - parser.print_help() - return 1 - - elif args.command == "mcp": - if args.mcp_command == "discover": - if args.discover_command == "hosts": - return handle_mcp_discover_hosts() - elif args.discover_command == "servers": - return handle_mcp_discover_servers(env_manager, args.env) - else: - print("Unknown discover command") - return 1 - - elif args.mcp_command == "list": - if args.list_command == "hosts": - return handle_mcp_list_hosts(env_manager, args.env, args.detailed) - elif args.list_command == "servers": - return handle_mcp_list_servers(env_manager, args.env) - else: - print("Unknown list command") - return 1 - - elif args.mcp_command == "backup": - if args.backup_command == "restore": - return handle_mcp_backup_restore( - env_manager, - args.host, - args.backup_file, - args.dry_run, - args.auto_approve, - ) - elif args.backup_command == "list": - return handle_mcp_backup_list(args.host, args.detailed) - elif args.backup_command == "clean": - return handle_mcp_backup_clean( - args.host, - args.older_than_days, - args.keep_count, - args.dry_run, - args.auto_approve, - ) - else: - print("Unknown backup command") - return 1 - - elif args.mcp_command == "configure": - return handle_mcp_configure( - args.host, - args.server_name, - args.server_command, - args.args, - getattr(args, "env_var", None), - args.url, - args.header, - getattr(args, "timeout", None), - getattr(args, "trust", False), - getattr(args, "cwd", None), - getattr(args, "env_file", None), - getattr(args, "http_url", None), - getattr(args, "include_tools", None), - getattr(args, "exclude_tools", None), - getattr(args, "input", None), - getattr(args, "disabled", None), - getattr(args, "auto_approve_tools", None), - getattr(args, "disable_tools", None), - getattr(args, "env_vars", None), - getattr(args, "startup_timeout", None), - getattr(args, "tool_timeout", None), - getattr(args, "enabled", None), - getattr(args, "bearer_token_env_var", None), - getattr(args, "env_header", None), - args.no_backup, - args.dry_run, - args.auto_approve, - ) - - elif args.mcp_command == "remove": - if args.remove_command == "server": - return handle_mcp_remove_server( - env_manager, - args.server_name, - args.host, - args.env, - args.no_backup, - args.dry_run, - args.auto_approve, - ) - elif args.remove_command == "host": - return handle_mcp_remove_host( - env_manager, - args.host_name, - args.no_backup, - args.dry_run, - args.auto_approve, - ) - else: - print("Unknown remove command") - return 1 - - elif args.mcp_command == "sync": - return handle_mcp_sync( - from_env=getattr(args, "from_env", None), - from_host=getattr(args, "from_host", None), - to_hosts=args.to_host, - servers=getattr(args, "servers", None), - pattern=getattr(args, "pattern", None), - dry_run=args.dry_run, - auto_approve=args.auto_approve, - no_backup=args.no_backup, - ) - - else: - print("Unknown MCP command") - return 1 - - else: - parser.print_help() - return 1 - - return 0 +# Issue deprecation warning after imports to avoid affecting import behavior +import warnings +warnings.warn( + "hatch.cli_hatch is deprecated since version 0.7.2. " + "Import from hatch.cli instead. " + "This module will be removed in version 0.9.0.", + DeprecationWarning, + stacklevel=2, +) -if __name__ == "__main__": - sys.exit(main()) +__all__ = [ + # Entry point + "main", + # Exit codes + "EXIT_SUCCESS", + "EXIT_ERROR", + # Utilities + "get_hatch_version", + "request_confirmation", + "parse_env_vars", + "parse_header", + "parse_input", + "parse_host_list", + "get_package_mcp_server_config", + # MCP handlers + "handle_mcp_discover_hosts", + "handle_mcp_discover_servers", + "handle_mcp_list_hosts", + "handle_mcp_list_servers", + "handle_mcp_backup_restore", + "handle_mcp_backup_list", + "handle_mcp_backup_clean", + "handle_mcp_configure", + "handle_mcp_remove", + "handle_mcp_remove_server", + "handle_mcp_remove_host", + "handle_mcp_sync", + # Environment handlers + "handle_env_create", + "handle_env_remove", + "handle_env_list", + "handle_env_use", + "handle_env_current", + "handle_env_show", + "handle_env_python_init", + "handle_env_python_info", + "handle_env_python_remove", + "handle_env_python_shell", + "handle_env_python_add_hatch_mcp", + # Package handlers + "handle_package_add", + "handle_package_remove", + "handle_package_list", + "handle_package_sync", + # System handlers + "handle_create", + "handle_validate", + # Types + "HatchEnvironmentManager", + "MCPHostConfigurationManager", + "MCPHostRegistry", + "MCPHostType", + "MCPServerConfig", +] diff --git a/hatch/environment_manager.py b/hatch/environment_manager.py index 585bdc7..19a5e6f 100644 --- a/hatch/environment_manager.py +++ b/hatch/environment_manager.py @@ -3,51 +3,62 @@ This module provides the core functionality for managing isolated environments for Hatch packages. """ + import sys import json import logging import datetime from pathlib import Path -from typing import Dict, List, Optional, Any, Tuple +from typing import Dict, List, Optional, Any -from hatch_validator.registry.registry_service import RegistryService, RegistryError +from hatch_validator.registry.registry_service import RegistryService from hatch.registry_retriever import RegistryRetriever from hatch_validator.package.package_service import PackageService from hatch.package_loader import HatchPackageLoader -from hatch.installers.dependency_installation_orchestrator import DependencyInstallerOrchestrator +from hatch.installers.dependency_installation_orchestrator import ( + DependencyInstallerOrchestrator, +) from hatch.installers.installation_context import InstallationContext -from hatch.python_environment_manager import PythonEnvironmentManager, PythonEnvironmentError +from hatch.python_environment_manager import ( + PythonEnvironmentManager, + PythonEnvironmentError, +) from hatch.mcp_host_config.models import MCPServerConfig + class HatchEnvironmentError(Exception): """Exception raised for environment-related errors.""" + pass class HatchEnvironmentManager: """Manages Hatch environments for package installation and isolation. - + This class handles: 1. Creating and managing isolated environments - 2. Environment lifecycle and state management + 2. Environment lifecycle and state management 3. Delegating package installation to the DependencyInstallerOrchestrator 4. Managing environment metadata and persistence """ - def __init__(self, - environments_dir: Optional[Path] = None, - cache_ttl: int = 86400, # Default TTL is 24 hours - cache_dir: Optional[Path] = None, - simulation_mode: bool = False, - local_registry_cache_path: Optional[Path] = None): + + def __init__( + self, + environments_dir: Optional[Path] = None, + cache_ttl: int = 86400, # Default TTL is 24 hours + cache_dir: Optional[Path] = None, + simulation_mode: bool = False, + local_registry_cache_path: Optional[Path] = None, + ): """Initialize the Hatch environment manager. - + Args: environments_dir (Path, optional): Directory to store environments. Defaults to ~/.hatch/envs. cache_ttl (int): Time-to-live for cache in seconds. Defaults to 86400 (24 hours). cache_dir (Path, optional): Directory to store local cache files. Defaults to ~/.hatch. simulation_mode (bool): Whether to operate in local simulation mode. Defaults to False. local_registry_cache_path (Path, optional): Path to local registry file. Defaults to None. - + """ self.logger = logging.getLogger("hatch.environment_manager") @@ -58,26 +69,29 @@ def __init__(self, self.environments_file = self.environments_dir / "environments.json" self.current_env_file = self.environments_dir / "current_env" - - + # Initialize Python environment manager - self.python_env_manager = PythonEnvironmentManager(environments_dir=self.environments_dir) - + self.python_env_manager = PythonEnvironmentManager( + environments_dir=self.environments_dir + ) + # Initialize dependencies self.package_loader = HatchPackageLoader(cache_dir=cache_dir) - self.retriever = RegistryRetriever(cache_ttl=cache_ttl, - local_cache_dir=cache_dir, - simulation_mode=simulation_mode, - local_registry_cache_path=local_registry_cache_path) + self.retriever = RegistryRetriever( + cache_ttl=cache_ttl, + local_cache_dir=cache_dir, + simulation_mode=simulation_mode, + local_registry_cache_path=local_registry_cache_path, + ) self.registry_data = self.retriever.get_registry() - + # Initialize services for dependency management self.registry_service = RegistryService(self.registry_data) - + self.dependency_orchestrator = DependencyInstallerOrchestrator( package_loader=self.package_loader, registry_service=self.registry_service, - registry_data=self.registry_data + registry_data=self.registry_data, ) # Load environments into cache @@ -89,19 +103,19 @@ def __init__(self, def _initialize_environments_file(self): """Create the initial environments file with default environment.""" default_environments = {} - - with open(self.environments_file, 'w') as f: + + with open(self.environments_file, "w") as f: json.dump(default_environments, f, indent=2) - + self.logger.info("Initialized environments file with default environment") - + def _initialize_current_env_file(self): """Create the current environment file pointing to the default environment.""" - with open(self.current_env_file, 'w') as f: + with open(self.current_env_file, "w") as f: f.write("default") - + self.logger.info("Initialized current environment to default") - + def _load_environments(self) -> Dict: """Load environments from the environments file. @@ -114,17 +128,19 @@ def _load_environments(self) -> Dict: """ try: - with open(self.environments_file, 'r') as f: + with open(self.environments_file, "r") as f: return json.load(f) except (json.JSONDecodeError, FileNotFoundError) as e: - self.logger.info(f"Failed to load environments: {e}. Initializing with default environment.") - + self.logger.info( + f"Failed to load environments: {e}. Initializing with default environment." + ) + # Touch the files with default values self._initialize_environments_file() self._initialize_current_env_file() # Load created default environment - with open(self.environments_file, 'r') as f: + with open(self.environments_file, "r") as f: _environments = json.load(f) # Assign to cache @@ -135,39 +151,38 @@ def _load_environments(self) -> Dict: return _environments - def _load_current_env_name(self) -> str: """Load current environment name from disk.""" try: - with open(self.current_env_file, 'r') as f: + with open(self.current_env_file, "r") as f: return f.read().strip() except FileNotFoundError: self._initialize_current_env_file() return "default" - + def get_environments(self) -> Dict: """Get environments from cache.""" return self._environments - + def reload_environments(self): """Reload environments from disk.""" self._environments = self._load_environments() self._current_env_name = self._load_current_env_name() self.logger.info("Reloaded environments from disk") - + def _save_environments(self): """Save environments to the environments file.""" try: - with open(self.environments_file, 'w') as f: + with open(self.environments_file, "w") as f: json.dump(self._environments, f, indent=2) except Exception as e: self.logger.error(f"Failed to save environments: {e}") raise HatchEnvironmentError(f"Failed to save environments: {e}") - + def get_current_environment(self) -> str: """Get the name of the current environment from cache.""" return self._current_env_name - + def get_current_environment_data(self) -> Dict: """Get the data for the current environment.""" return self._environments[self._current_env_name] @@ -185,14 +200,14 @@ def get_environment_data(self, env_name: str) -> Dict: KeyError: If environment doesn't exist """ return self._environments[env_name] - + def set_current_environment(self, env_name: str) -> bool: """ Set the current environment. - + Args: env_name: Name of the environment to set as current - + Returns: bool: True if successful, False if environment doesn't exist """ @@ -200,80 +215,86 @@ def set_current_environment(self, env_name: str) -> bool: if env_name not in self._environments: self.logger.error(f"Environment does not exist: {env_name}") return False - + # Set current environment try: - with open(self.current_env_file, 'w') as f: + with open(self.current_env_file, "w") as f: f.write(env_name) - + # Update cache self._current_env_name = env_name - + # Configure Python executable for dependency installation self._configure_python_executable(env_name) - + self.logger.info(f"Current environment set to: {env_name}") return True except Exception as e: self.logger.error(f"Failed to set current environment: {e}") return False - + def _configure_python_executable(self, env_name: str) -> None: """Configure the Python executable for the current environment. - + This method sets the Python executable in the dependency orchestrator's InstallationContext so that python_installer.py uses the correct interpreter. - + Args: env_name: Name of the environment to configure Python for """ # Get Python executable from Python environment manager python_executable = self.python_env_manager.get_python_executable(env_name) - + if python_executable: # Configure the dependency orchestrator with the Python executable - python_env_vars = self.python_env_manager.get_environment_activation_info(env_name) + python_env_vars = self.python_env_manager.get_environment_activation_info( + env_name + ) self.dependency_orchestrator.set_python_env_vars(python_env_vars) else: # Use system Python as fallback system_python = sys.executable python_env_vars = {"PYTHON": system_python} self.dependency_orchestrator.set_python_env_vars(python_env_vars) - + def get_current_python_executable(self) -> Optional[str]: """Get the Python executable for the current environment. - + Returns: str: Path to Python executable, None if no current environment or no Python env """ if not self._current_env_name: return None - + return self.python_env_manager.get_python_executable(self._current_env_name) - + def list_environments(self) -> List[Dict]: """ List all available environments. - + Returns: List[Dict]: List of environment information dictionaries """ result = [] for name, env_data in self._environments.items(): env_info = env_data.copy() - env_info["is_current"] = (name == self._current_env_name) + env_info["is_current"] = name == self._current_env_name result.append(env_info) - + return result - - def create_environment(self, name: str, description: str = "", - python_version: Optional[str] = None, - create_python_env: bool = True, - no_hatch_mcp_server: bool = False, - hatch_mcp_server_tag: Optional[str] = None) -> bool: + + def create_environment( + self, + name: str, + description: str = "", + python_version: Optional[str] = None, + create_python_env: bool = True, + no_hatch_mcp_server: bool = False, + hatch_mcp_server_tag: Optional[str] = None, + ) -> bool: """ Create a new environment. - + Args: name: Name of the environment description: Description of the environment @@ -281,20 +302,20 @@ def create_environment(self, name: str, description: str = "", create_python_env: Whether to create a Python environment using conda/mamba no_hatch_mcp_server: Whether to skip installing hatch_mcp_server in the environment hatch_mcp_server_tag: Git tag/branch reference for hatch_mcp_server installation - + Returns: bool: True if created successfully, False if environment already exists """ # Allow alphanumeric characters and underscores - if not name or not all(c.isalnum() or c == '_' for c in name): + if not name or not all(c.isalnum() or c == "_" for c in name): self.logger.error("Environment name must be alphanumeric or underscore") return False - + # Check if environment already exists if name in self._environments: self.logger.warning(f"Environment already exists: {name}") return False - + # Create Python environment if requested and conda/mamba is available python_env_info = None if create_python_env and self.python_env_manager.is_available(): @@ -304,7 +325,7 @@ def create_environment(self, name: str, description: str = "", ) if python_env_created: self.logger.info(f"Created Python environment for {name}") - + # Get detailed Python environment information python_info = self.python_env_manager.get_environment_info(name) if python_info: @@ -315,7 +336,7 @@ def create_environment(self, name: str, description: str = "", "created_at": datetime.datetime.now().isoformat(), "version": python_info.get("python_version"), "requested_version": python_version, - "manager": python_info.get("manager", "conda") + "manager": python_info.get("manager", "conda"), } else: # Fallback if detailed info is not available @@ -326,134 +347,161 @@ def create_environment(self, name: str, description: str = "", "created_at": datetime.datetime.now().isoformat(), "version": None, "requested_version": python_version, - "manager": "conda" + "manager": "conda", } else: - self.logger.warning(f"Failed to create Python environment for {name}") + self.logger.warning( + f"Failed to create Python environment for {name}" + ) except PythonEnvironmentError as e: self.logger.error(f"Failed to create Python environment: {e}") # Continue with Hatch environment creation even if Python env creation fails elif create_python_env: - self.logger.warning("Python environment creation requested but conda/mamba not available") - + self.logger.warning( + "Python environment creation requested but conda/mamba not available" + ) + # Create new Hatch environment with enhanced metadata env_data = { "name": name, "description": description, "created_at": datetime.datetime.now().isoformat(), "packages": [], - "python_environment": python_env_info is not None, # Legacy field for backward compatibility + "python_environment": python_env_info + is not None, # Legacy field for backward compatibility "python_version": python_version, # Legacy field for backward compatibility - "python_env": python_env_info # Enhanced metadata structure + "python_env": python_env_info, # Enhanced metadata structure } - + self._environments[name] = env_data - + self._save_environments() self.logger.info(f"Created environment: {name}") - + # Install hatch_mcp_server by default unless opted out if not no_hatch_mcp_server and python_env_info is not None: try: self._install_hatch_mcp_server(name, hatch_mcp_server_tag) except Exception as e: - self.logger.warning(f"Failed to install hatch_mcp_server wrapper in environment {name}: {e}") + self.logger.warning( + f"Failed to install hatch_mcp_server wrapper in environment {name}: {e}" + ) # Don't fail environment creation if MCP wrapper installation fails - + return True - - def _install_hatch_mcp_server(self, env_name: str, tag: Optional[str] = None) -> None: + + def _install_hatch_mcp_server( + self, env_name: str, tag: Optional[str] = None + ) -> None: """Install hatch_mcp_server wrapper package in the specified environment. - + Args: env_name (str): Name of the environment to install MCP wrapper in. tag (str, optional): Git tag/branch reference for the installation. Defaults to None (uses default branch). - + Raises: HatchEnvironmentError: If installation fails. """ try: # Construct the package URL with optional tag if tag: - package_git_url = f"git+https://github.com/CrackingShells/Hatch-MCP-Server.git@{tag}" + package_git_url = ( + f"git+https://github.com/CrackingShells/Hatch-MCP-Server.git@{tag}" + ) else: - package_git_url = "git+https://github.com/CrackingShells/Hatch-MCP-Server.git" - + package_git_url = ( + "git+https://github.com/CrackingShells/Hatch-MCP-Server.git" + ) + # Create dependency structure following the schema mcp_dep = { "name": f"hatch_mcp_server @ {package_git_url}", "version_constraint": "*", "package_manager": "pip", "type": "python", - "uri": package_git_url + "uri": package_git_url, } - + # Get environment path env_path = self.get_environment_path(env_name) - + # Create installation context context = InstallationContext( environment_path=env_path, environment_name=env_name, temp_dir=env_path / ".tmp", - cache_dir=self.package_loader.cache_dir if hasattr(self.package_loader, 'cache_dir') else None, + cache_dir=( + self.package_loader.cache_dir + if hasattr(self.package_loader, "cache_dir") + else None + ), parallel_enabled=False, force_reinstall=False, simulation_mode=False, extra_config={ "package_loader": self.package_loader, "registry_service": self.registry_service, - "registry_data": self.registry_data - } + "registry_data": self.registry_data, + }, ) - + # Configure Python environment variables if available python_executable = self.python_env_manager.get_python_executable(env_name) if python_executable: python_env_vars = {"PYTHON": python_executable} self.dependency_orchestrator.set_python_env_vars(python_env_vars) context.set_config("python_env_vars", python_env_vars) - + # Install using the orchestrator - self.logger.info(f"Installing hatch_mcp_server wrapper in environment {env_name}") + self.logger.info( + f"Installing hatch_mcp_server wrapper in environment {env_name}" + ) self.logger.info(f"Using python executable: {python_executable}") - installed_package = self.dependency_orchestrator.install_single_dep(mcp_dep, context) - + self.dependency_orchestrator.install_single_dep(mcp_dep, context) + self._save_environments() - self.logger.info(f"Successfully installed hatch_mcp_server wrapper in environment {env_name}") - + self.logger.info( + f"Successfully installed hatch_mcp_server wrapper in environment {env_name}" + ) + except Exception as e: self.logger.error(f"Failed to install hatch_mcp_server wrapper: {e}") - raise HatchEnvironmentError(f"Failed to install hatch_mcp_server wrapper: {e}") from e + raise HatchEnvironmentError( + f"Failed to install hatch_mcp_server wrapper: {e}" + ) from e - def install_mcp_server(self, env_name: Optional[str] = None, tag: Optional[str] = None) -> bool: + def install_mcp_server( + self, env_name: Optional[str] = None, tag: Optional[str] = None + ) -> bool: """Install hatch_mcp_server wrapper package in an existing environment. - + Args: env_name (str, optional): Name of the hatch environment. Uses current environment if None. tag (str, optional): Git tag/branch reference for the installation. Defaults to None (uses default branch). - + Returns: bool: True if installation succeeded, False otherwise. """ if env_name is None: env_name = self._current_env_name - + if not self.environment_exists(env_name): self.logger.error(f"Environment does not exist: {env_name}") return False - + # Check if environment has Python support env_data = self._environments[env_name] if not env_data.get("python_env"): self.logger.error(f"Environment {env_name} does not have Python support") return False - + try: self._install_hatch_mcp_server(env_name, tag) return True except Exception as e: - self.logger.error(f"Failed to install MCP wrapper in environment {env_name}: {e}") + self.logger.error( + f"Failed to install MCP wrapper in environment {env_name}: {e}" + ) return False def remove_environment(self, name: str) -> bool: @@ -484,9 +532,12 @@ def remove_environment(self, name: str) -> bool: env_data = self._environments[name] packages = env_data.get("packages", []) if packages: - self.logger.info(f"Cleaning up MCP server configurations for {len(packages)} packages in environment {name}") + self.logger.info( + f"Cleaning up MCP server configurations for {len(packages)} packages in environment {name}" + ) try: from .mcp_host_config.host_management import MCPHostConfigurationManager + mcp_manager = MCPHostConfigurationManager() for pkg in packages: @@ -500,20 +551,30 @@ def remove_environment(self, name: str) -> bool: result = mcp_manager.remove_server( server_name=package_name, # In current 1:1 design, package name = server name hostname=hostname, - no_backup=False # Create backup for safety + no_backup=False, # Create backup for safety ) if result.success: - self.logger.info(f"Removed MCP server '{package_name}' from host '{hostname}' (env removal)") + self.logger.info( + f"Removed MCP server '{package_name}' from host '{hostname}' (env removal)" + ) else: - self.logger.warning(f"Failed to remove MCP server '{package_name}' from host '{hostname}': {result.error_message}") + self.logger.warning( + f"Failed to remove MCP server '{package_name}' from host '{hostname}': {result.error_message}" + ) except Exception as e: - self.logger.warning(f"Error removing MCP server '{package_name}' from host '{hostname}': {e}") + self.logger.warning( + f"Error removing MCP server '{package_name}' from host '{hostname}': {e}" + ) except ImportError: - self.logger.warning("MCP host configuration manager not available for cleanup") + self.logger.warning( + "MCP host configuration manager not available for cleanup" + ) except Exception as e: - self.logger.warning(f"Error during MCP server cleanup for environment removal: {e}") + self.logger.warning( + f"Error during MCP server cleanup for environment removal: {e}" + ) # Remove Python environment if it exists if env_data.get("python_environment", False): @@ -530,27 +591,30 @@ def remove_environment(self, name: str) -> bool: self._save_environments() self.logger.info(f"Removed environment: {name}") return True - + def environment_exists(self, name: str) -> bool: """ Check if an environment exists. - + Args: name: Name of the environment to check - + Returns: bool: True if environment exists, False otherwise """ return name in self._environments - - def add_package_to_environment(self, package_path_or_name: str, - env_name: Optional[str] = None, - version_constraint: Optional[str] = None, - force_download: bool = False, - refresh_registry: bool = False, - auto_approve: bool = False) -> bool: + + def add_package_to_environment( + self, + package_path_or_name: str, + env_name: Optional[str] = None, + version_constraint: Optional[str] = None, + force_download: bool = False, + refresh_registry: bool = False, + auto_approve: bool = False, + ) -> bool: """Add a package to an environment. - + This method delegates all installation orchestration to the DependencyInstallerOrchestrator while maintaining responsibility for environment lifecycle and state management. @@ -558,42 +622,45 @@ def add_package_to_environment(self, package_path_or_name: str, package_path_or_name (str): Path to local package or name of remote package. env_name (str, optional): Environment to add to. Defaults to current environment. version_constraint (str, optional): Version constraint for remote packages. Defaults to None. - force_download (bool, optional): Force download even if package is cached. When True, + force_download (bool, optional): Force download even if package is cached. When True, bypass the package cache and download directly from the source. Defaults to False. - refresh_registry (bool, optional): Force refresh of registry data. When True, + refresh_registry (bool, optional): Force refresh of registry data. When True, fetch the latest registry data before resolving dependencies. Defaults to False. auto_approve (bool, optional): Skip user consent prompt for automation scenarios. Defaults to False. - + Returns: bool: True if successful, False otherwise. - """ + """ env_name = env_name or self._current_env_name - + if not self.environment_exists(env_name): self.logger.error(f"Environment {env_name} does not exist") return False - + # Refresh registry if requested if refresh_registry: self.refresh_registry(force_refresh=True) - + try: # Get currently installed packages for filtering existing_packages = {} for pkg in self._environments[env_name].get("packages", []): existing_packages[pkg["name"]] = pkg["version"] - + # Delegate installation to orchestrator - success, installed_packages = self.dependency_orchestrator.install_dependencies( + ( + success, + installed_packages, + ) = self.dependency_orchestrator.install_dependencies( package_path_or_name=package_path_or_name, env_path=self.get_environment_path(env_name), env_name=env_name, existing_packages=existing_packages, version_constraint=version_constraint, force_download=force_download, - auto_approve=auto_approve + auto_approve=auto_approve, ) - + if success: # Update environment metadata with installed Hatch packages for pkg_info in installed_packages: @@ -603,26 +670,33 @@ def add_package_to_environment(self, package_path_or_name: str, package_name=pkg_info["name"], package_version=pkg_info["version"], package_type=pkg_info["type"], - source=pkg_info["source"] + source=pkg_info["source"], ) - - self.logger.info(f"Successfully installed {len(installed_packages)} packages to environment {env_name}") + + self.logger.info( + f"Successfully installed {len(installed_packages)} packages to environment {env_name}" + ) return True else: self.logger.info("Package installation was cancelled or failed") return False - + except Exception as e: self.logger.error(f"Failed to add package to environment: {e}") return False - def _add_package_to_env_data(self, env_name: str, package_name: str, - package_version: str, package_type: str, - source: str) -> None: + def _add_package_to_env_data( + self, + env_name: str, + package_name: str, + package_version: str, + package_type: str, + source: str, + ) -> None: """Update environment data with package information.""" if env_name not in self._environments: raise HatchEnvironmentError(f"Environment {env_name} does not exist") - + # Check if package already exists for i, pkg in enumerate(self._environments[env_name].get("packages", [])): if pkg.get("name") == package_name: @@ -632,24 +706,27 @@ def _add_package_to_env_data(self, env_name: str, package_name: str, "version": package_version, "type": package_type, "source": source, - "installed_at": datetime.datetime.now().isoformat() + "installed_at": datetime.datetime.now().isoformat(), } self._save_environments() return - + # if it doesn't exist add new package entry - self._environments[env_name]["packages"] += [{ - "name": package_name, - "version": package_version, - "type": package_type, - "source": source, - "installed_at": datetime.datetime.now().isoformat() - }] + self._environments[env_name]["packages"] += [ + { + "name": package_name, + "version": package_version, + "type": package_type, + "source": source, + "installed_at": datetime.datetime.now().isoformat(), + } + ] self._save_environments() - def update_package_host_configuration(self, env_name: str, package_name: str, - hostname: str, server_config: dict) -> bool: + def update_package_host_configuration( + self, env_name: str, package_name: str, hostname: str, server_config: dict + ) -> bool: """Update package metadata with host configuration tracking. Enforces constraint: Only one environment can control a package-host combination. @@ -671,9 +748,7 @@ def update_package_host_configuration(self, env_name: str, package_name: str, # Step 1: Clean up conflicting configurations from other environments conflicts_removed = self._cleanup_package_host_conflicts( - target_env=env_name, - package_name=package_name, - hostname=hostname + target_env=env_name, package_name=package_name, hostname=hostname ) # Step 2: Update target environment configuration @@ -694,7 +769,9 @@ def update_package_host_configuration(self, env_name: str, package_name: str, self.logger.error(f"Failed to update package host configuration: {e}") return False - def _cleanup_package_host_conflicts(self, target_env: str, package_name: str, hostname: str) -> int: + def _cleanup_package_host_conflicts( + self, target_env: str, package_name: str, hostname: str + ) -> int: """Remove conflicting package-host configurations from other environments. This method enforces the constraint that only one environment can control @@ -738,8 +815,9 @@ def _cleanup_package_host_conflicts(self, target_env: str, package_name: str, ho return conflicts_removed - def _update_target_environment_configuration(self, env_name: str, package_name: str, - hostname: str, server_config: dict) -> bool: + def _update_target_environment_configuration( + self, env_name: str, package_name: str, hostname: str, server_config: dict + ) -> bool: """Update the target environment's package host configuration. This method handles the actual configuration update for the target environment @@ -764,24 +842,29 @@ def _update_target_environment_configuration(self, env_name: str, package_name: # Add or update host configuration from datetime import datetime + pkg["configured_hosts"][hostname] = { "config_path": self._get_host_config_path(hostname), "configured_at": datetime.now().isoformat(), "last_synced": datetime.now().isoformat(), - "server_config": server_config + "server_config": server_config, } # Update the package in the environment self._environments[env_name]["packages"][i] = pkg self._save_environments() - self.logger.info(f"Updated host configuration for package {package_name} on {hostname}") + self.logger.info( + f"Updated host configuration for package {package_name} on {hostname}" + ) return True self.logger.error(f"Package {package_name} not found in environment {env_name}") return False - def remove_package_host_configuration(self, env_name: str, package_name: str, hostname: str) -> bool: + def remove_package_host_configuration( + self, env_name: str, package_name: str, hostname: str + ) -> bool: """Remove host configuration tracking for a specific package. Args: @@ -804,7 +887,9 @@ def remove_package_host_configuration(self, env_name: str, package_name: str, ho if hostname in configured_hosts: del configured_hosts[hostname] self._save_environments() - self.logger.info(f"Removed host {hostname} from package {package_name} in env {env_name}") + self.logger.info( + f"Removed host {hostname} from package {package_name} in env {env_name}" + ) return True return False @@ -832,7 +917,9 @@ def clear_host_from_all_packages_all_envs(self, hostname: str) -> int: if hostname in configured_hosts: del configured_hosts[hostname] updates_count += 1 - self.logger.info(f"Removed host {hostname} from package {pkg.get('name')} in env {env_name}") + self.logger.info( + f"Removed host {hostname} from package {pkg.get('name')} in env {env_name}" + ) if updates_count > 0: self._save_environments() @@ -843,7 +930,9 @@ def clear_host_from_all_packages_all_envs(self, hostname: str) -> int: self.logger.error(f"Failed to clear host from all packages: {e}") return 0 - def apply_restored_host_configuration_to_environments(self, hostname: str, restored_servers: Dict[str, MCPServerConfig]) -> int: + def apply_restored_host_configuration_to_environments( + self, hostname: str, restored_servers: Dict[str, MCPServerConfig] + ) -> int: """Update environment tracking to match restored host configuration. Args: @@ -857,6 +946,7 @@ def apply_restored_host_configuration_to_environments(self, hostname: str, resto try: from datetime import datetime + current_time = datetime.now().isoformat() for env_name, env_data in self._environments.items(): @@ -871,18 +961,26 @@ def apply_restored_host_configuration_to_environments(self, hostname: str, resto server_config = restored_servers[package_name] configured_hosts[hostname] = { "config_path": self._get_host_config_path(hostname), - "configured_at": configured_hosts.get(hostname, {}).get("configured_at", current_time), + "configured_at": configured_hosts.get(hostname, {}).get( + "configured_at", current_time + ), "last_synced": current_time, - "server_config": server_config.model_dump(exclude_none=True) + "server_config": server_config.model_dump( + exclude_none=True + ), } updates_count += 1 - self.logger.info(f"Updated host {hostname} tracking for package {package_name} in env {env_name}") + self.logger.info( + f"Updated host {hostname} tracking for package {package_name} in env {env_name}" + ) elif hostname in configured_hosts: # Server not in restored config but was previously tracked - remove stale tracking del configured_hosts[hostname] updates_count += 1 - self.logger.info(f"Removed stale host {hostname} tracking for package {package_name} in env {env_name}") + self.logger.info( + f"Removed stale host {hostname} tracking for package {package_name} in env {env_name}" + ) if updates_count > 0: self._save_environments() @@ -904,53 +1002,53 @@ def _get_host_config_path(self, hostname: str) -> str: """ # Map hostnames to their typical config paths host_config_paths = { - 'gemini': '~/.gemini/settings.json', - 'claude-desktop': '~/.claude/claude_desktop_config.json', - 'claude-code': '.claude/mcp_config.json', - 'vscode': '.vscode/settings.json', - 'cursor': '~/.cursor/mcp.json', - 'lmstudio': '~/.lmstudio/mcp.json' + "gemini": "~/.gemini/settings.json", + "claude-desktop": "~/.claude/claude_desktop_config.json", + "claude-code": ".claude/mcp_config.json", + "vscode": ".vscode/settings.json", + "cursor": "~/.cursor/mcp.json", + "lmstudio": "~/.lmstudio/mcp.json", } - return host_config_paths.get(hostname, f'~/.{hostname}/config.json') + return host_config_paths.get(hostname, f"~/.{hostname}/config.json") def get_environment_path(self, env_name: str) -> Path: """ Get the path to the environment directory. - + Args: env_name: Name of the environment - + Returns: Path: Path to the environment directory - + Raises: HatchEnvironmentError: If environment doesn't exist """ if not self.environment_exists(env_name): raise HatchEnvironmentError(f"Environment {env_name} does not exist") - + env_path = self.environments_dir / env_name env_path.mkdir(exist_ok=True) return env_path - + def list_packages(self, env_name: Optional[str] = None) -> List[Dict]: """ List all packages installed in an environment. - + Args: env_name: Name of the environment (uses current if None) - + Returns: List[Dict]: List of package information dictionaries - + Raises: HatchEnvironmentError: If environment doesn't exist """ env_name = env_name or self._current_env_name if not self.environment_exists(env_name): raise HatchEnvironmentError(f"Environment {env_name} does not exist") - + packages = [] for pkg in self._environments[env_name].get("packages", []): # Add full package info including paths @@ -959,17 +1057,17 @@ def list_packages(self, env_name: Optional[str] = None) -> List[Dict]: # Check if the package is Hatch compliant (has hatch_metadata.json) pkg_path = self.get_environment_path(env_name) / pkg["name"] pkg_info["hatch_compliant"] = (pkg_path / "hatch_metadata.json").exists() - + # Add source information pkg_info["source"] = { "uri": pkg.get("source", "unknown"), - "path": str(pkg_path) + "path": str(pkg_path), } - + packages.append(pkg_info) - + return packages - + def remove_package(self, package_name: str, env_name: Optional[str] = None) -> bool: """ Remove a package from an environment. @@ -997,15 +1095,20 @@ def remove_package(self, package_name: str, env_name: Optional[str] = None) -> b break if pkg_index is None: - self.logger.warning(f"Package {package_name} not found in environment {env_name}") + self.logger.warning( + f"Package {package_name} not found in environment {env_name}" + ) return False # Clean up MCP server configurations from all configured hosts configured_hosts = package_to_remove.get("configured_hosts", {}) if configured_hosts: - self.logger.info(f"Cleaning up MCP server configurations for package {package_name}") + self.logger.info( + f"Cleaning up MCP server configurations for package {package_name}" + ) try: from .mcp_host_config.host_management import MCPHostConfigurationManager + mcp_manager = MCPHostConfigurationManager() for hostname in configured_hosts.keys(): @@ -1014,18 +1117,26 @@ def remove_package(self, package_name: str, env_name: Optional[str] = None) -> b result = mcp_manager.remove_server( server_name=package_name, # In current 1:1 design, package name = server name hostname=hostname, - no_backup=False # Create backup for safety + no_backup=False, # Create backup for safety ) if result.success: - self.logger.info(f"Removed MCP server '{package_name}' from host '{hostname}'") + self.logger.info( + f"Removed MCP server '{package_name}' from host '{hostname}'" + ) else: - self.logger.warning(f"Failed to remove MCP server '{package_name}' from host '{hostname}': {result.error_message}") + self.logger.warning( + f"Failed to remove MCP server '{package_name}' from host '{hostname}': {result.error_message}" + ) except Exception as e: - self.logger.warning(f"Error removing MCP server '{package_name}' from host '{hostname}': {e}") + self.logger.warning( + f"Error removing MCP server '{package_name}' from host '{hostname}': {e}" + ) except ImportError: - self.logger.warning("MCP host configuration manager not available for cleanup") + self.logger.warning( + "MCP host configuration manager not available for cleanup" + ) except Exception as e: self.logger.warning(f"Error during MCP server cleanup: {e}") @@ -1033,6 +1144,7 @@ def remove_package(self, package_name: str, env_name: Optional[str] = None) -> b pkg_path = self.get_environment_path(env_name) / package_name try: import shutil + if pkg_path.exists(): shutil.rmtree(pkg_path) except Exception as e: @@ -1049,172 +1161,203 @@ def remove_package(self, package_name: str, env_name: Optional[str] = None) -> b def get_servers_entry_points(self, env_name: Optional[str] = None) -> List[str]: """ Get the list of entry points for the MCP servers of each package in an environment. - + Args: env_name: Environment to get servers from (uses current if None) - + Returns: List[str]: List of server entry points """ env_name = env_name or self._current_env_name if not self.environment_exists(env_name): raise HatchEnvironmentError(f"Environment {env_name} does not exist") - + ep = [] for pkg in self._environments[env_name].get("packages", []): # Open the package's metadata file - with open(self.environments_dir / env_name / pkg["name"] / "hatch_metadata.json", 'r') as f: + with open( + self.environments_dir / env_name / pkg["name"] / "hatch_metadata.json", + "r", + ) as f: hatch_metadata = json.load(f) package_service = PackageService(hatch_metadata) # retrieve entry points - ep += [(self.environments_dir / env_name / pkg["name"] / package_service.get_hatch_mcp_entry_point()).resolve()] + ep += [ + ( + self.environments_dir + / env_name + / pkg["name"] + / package_service.get_hatch_mcp_entry_point() + ).resolve() + ] return ep def refresh_registry(self, force_refresh: bool = True) -> None: """Refresh the registry data from the source. - + This method forces a refresh of the registry data to ensure the environment manager has the most recent package information available. After refreshing, it updates the orchestrator and associated services to use the new registry data. - + Args: force_refresh (bool, optional): Force refresh the registry even if cache is valid. When True, bypasses all caching mechanisms and fetches directly from source. Defaults to True. - + Raises: Exception: If fetching the registry data fails for any reason. """ self.logger.info("Refreshing registry data...") try: - self.registry_data = self.retriever.get_registry(force_refresh=force_refresh) + self.registry_data = self.retriever.get_registry( + force_refresh=force_refresh + ) # Update registry service with new registry data self.registry_service = RegistryService(self.registry_data) - + # Update orchestrator with new registry data self.dependency_orchestrator.registry_service = self.registry_service self.dependency_orchestrator.registry_data = self.registry_data - + self.logger.info("Registry data refreshed successfully") except Exception as e: self.logger.error(f"Failed to refresh registry data: {e}") raise - + def is_python_environment_available(self) -> bool: """Check if Python environment management is available. - + Returns: bool: True if conda/mamba is available, False otherwise. """ return self.python_env_manager.is_available() - - def get_python_environment_info(self, env_name: Optional[str] = None) -> Optional[Dict[str, Any]]: + + def get_python_environment_info( + self, env_name: Optional[str] = None + ) -> Optional[Dict[str, Any]]: """Get comprehensive Python environment information for an environment. - + Args: env_name (str, optional): Environment name. Defaults to current environment. - + Returns: dict: Comprehensive Python environment info, None if no Python environment exists. - + Raises: HatchEnvironmentError: If no environment name provided and no current environment set. """ if env_name is None: env_name = self.get_current_environment() if not env_name: - raise HatchEnvironmentError("No environment name provided and no current environment set") - + raise HatchEnvironmentError( + "No environment name provided and no current environment set" + ) + if env_name not in self._environments: return None - + env_data = self._environments[env_name] - + # Check if Python environment exists if not env_data.get("python_environment", False): return None - + # Start with enhanced metadata from Hatch environment python_env_data = env_data.get("python_env", {}) - + # Get real-time information from Python environment manager live_info = self.python_env_manager.get_environment_info(env_name) - + # Combine metadata with live information result = { # Basic identification "environment_name": env_name, "enabled": python_env_data.get("enabled", True), - # Conda/mamba information - "conda_env_name": python_env_data.get("conda_env_name") or (live_info.get("conda_env_name") if live_info else None), + "conda_env_name": python_env_data.get("conda_env_name") + or (live_info.get("conda_env_name") if live_info else None), "manager": python_env_data.get("manager", "conda"), - # Python executable and version - "python_executable": live_info.get("python_executable") if live_info else python_env_data.get("python_executable"), - "python_version": live_info.get("python_version") if live_info else python_env_data.get("version"), + "python_executable": ( + live_info.get("python_executable") + if live_info + else python_env_data.get("python_executable") + ), + "python_version": ( + live_info.get("python_version") + if live_info + else python_env_data.get("version") + ), "requested_version": python_env_data.get("requested_version"), - # Paths and timestamps - "environment_path": live_info.get("environment_path") if live_info else None, + "environment_path": ( + live_info.get("environment_path") if live_info else None + ), "created_at": python_env_data.get("created_at"), - # Package information "package_count": live_info.get("package_count", 0) if live_info else 0, "packages": live_info.get("packages", []) if live_info else [], - # Status information "exists": live_info is not None, - "accessible": live_info.get("python_executable") is not None if live_info else False + "accessible": ( + live_info.get("python_executable") is not None if live_info else False + ), } - + return result - + def list_python_environments(self) -> List[str]: """List all environments that have Python environments. - + Returns: list: List of environment names with Python environments. """ return self.python_env_manager.list_environments() - - def create_python_environment_only(self, env_name: Optional[str] = None, python_version: Optional[str] = None, - force: bool = False, no_hatch_mcp_server: bool = False, - hatch_mcp_server_tag: Optional[str] = None) -> bool: + + def create_python_environment_only( + self, + env_name: Optional[str] = None, + python_version: Optional[str] = None, + force: bool = False, + no_hatch_mcp_server: bool = False, + hatch_mcp_server_tag: Optional[str] = None, + ) -> bool: """Create only a Python environment without creating a Hatch environment. - + Useful for adding Python environments to existing Hatch environments. - + Args: env_name (str, optional): Environment name. Defaults to current environment. python_version (str, optional): Python version (e.g., "3.11"). Defaults to None. force (bool, optional): Whether to recreate if exists. Defaults to False. no_hatch_mcp_server (bool, optional): Whether to skip installing hatch_mcp_server wrapper in the environment. Defaults to False. hatch_mcp_server_tag (str, optional): Git tag/branch reference for hatch_mcp_server wrapper installation. Defaults to None. - + Returns: bool: True if successful, False otherwise. - + Raises: HatchEnvironmentError: If no environment name provided and no current environment set. """ if env_name is None: env_name = self.get_current_environment() if not env_name: - raise HatchEnvironmentError("No environment name provided and no current environment set") - + raise HatchEnvironmentError( + "No environment name provided and no current environment set" + ) + if env_name not in self._environments: self.logger.error(f"Hatch environment {env_name} must exist first") return False - + try: success = self.python_env_manager.create_python_environment( env_name, python_version=python_version, force=force ) - + if success: # Get detailed Python environment information python_info = self.python_env_manager.get_environment_info(env_name) @@ -1226,7 +1369,7 @@ def create_python_environment_only(self, env_name: Optional[str] = None, python_ "created_at": datetime.datetime.now().isoformat(), "version": python_info.get("python_version"), "requested_version": python_version, - "manager": python_info.get("manager", "conda") + "manager": python_info.get("manager", "conda"), } else: # Fallback if detailed info is not available @@ -1237,102 +1380,120 @@ def create_python_environment_only(self, env_name: Optional[str] = None, python_ "created_at": datetime.datetime.now().isoformat(), "version": None, "requested_version": python_version, - "manager": "conda" + "manager": "conda", } - + # Update environment metadata with enhanced structure - self._environments[env_name]["python_environment"] = True # Legacy field - self._environments[env_name]["python_env"] = python_env_info # Enhanced structure + self._environments[env_name][ + "python_environment" + ] = True # Legacy field + self._environments[env_name][ + "python_env" + ] = python_env_info # Enhanced structure if python_version: - self._environments[env_name]["python_version"] = python_version # Legacy field + self._environments[env_name][ + "python_version" + ] = python_version # Legacy field self._save_environments() - + # Reconfigure Python executable if this is the current environment if env_name == self._current_env_name: self._configure_python_executable(env_name) - + # Install hatch_mcp_server by default unless opted out if not no_hatch_mcp_server: try: self._install_hatch_mcp_server(env_name, hatch_mcp_server_tag) except Exception as e: - self.logger.warning(f"Failed to install hatch_mcp_server wrapper in environment {env_name}: {e}") + self.logger.warning( + f"Failed to install hatch_mcp_server wrapper in environment {env_name}: {e}" + ) # Don't fail environment creation if MCP wrapper installation fails - + return success except PythonEnvironmentError as e: self.logger.error(f"Failed to create Python environment: {e}") return False - + def remove_python_environment_only(self, env_name: Optional[str] = None) -> bool: """Remove only the Python environment, keeping the Hatch environment. - + Args: env_name (str, optional): Environment name. Defaults to current environment. - + Returns: bool: True if successful, False otherwise. - + Raises: HatchEnvironmentError: If no environment name provided and no current environment set. """ if env_name is None: env_name = self.get_current_environment() if not env_name: - raise HatchEnvironmentError("No environment name provided and no current environment set") - + raise HatchEnvironmentError( + "No environment name provided and no current environment set" + ) + if env_name not in self._environments: self.logger.warning(f"Hatch environment {env_name} does not exist") return False - + try: success = self.python_env_manager.remove_python_environment(env_name) - + if success: # Update environment metadata - remove Python environment info - self._environments[env_name]["python_environment"] = False # Legacy field + self._environments[env_name][ + "python_environment" + ] = False # Legacy field self._environments[env_name]["python_env"] = None # Enhanced structure - self._environments[env_name].pop("python_version", None) # Legacy field cleanup + self._environments[env_name].pop( + "python_version", None + ) # Legacy field cleanup self._save_environments() - + # Reconfigure Python executable if this is the current environment if env_name == self._current_env_name: self._configure_python_executable(env_name) - + return success except PythonEnvironmentError as e: self.logger.error(f"Failed to remove Python environment: {e}") return False - - def get_python_environment_diagnostics(self, env_name: Optional[str] = None) -> Optional[Dict[str, Any]]: + + def get_python_environment_diagnostics( + self, env_name: Optional[str] = None + ) -> Optional[Dict[str, Any]]: """Get detailed diagnostics for a Python environment. - + Args: env_name (str, optional): Environment name. Defaults to current environment. - + Returns: dict: Diagnostics information or None if environment doesn't exist. - + Raises: HatchEnvironmentError: If no environment name provided and no current environment set. """ if env_name is None: env_name = self.get_current_environment() if not env_name: - raise HatchEnvironmentError("No environment name provided and no current environment set") - + raise HatchEnvironmentError( + "No environment name provided and no current environment set" + ) + if env_name not in self._environments: return None - + try: return self.python_env_manager.get_environment_diagnostics(env_name) except PythonEnvironmentError as e: self.logger.error(f"Failed to get diagnostics for {env_name}: {e}") return None - + def get_python_manager_diagnostics(self) -> Dict[str, Any]: """Get general diagnostics for the Python environment manager. - + Returns: dict: General diagnostics information. """ @@ -1341,35 +1502,39 @@ def get_python_manager_diagnostics(self) -> Dict[str, Any]: except Exception as e: self.logger.error(f"Failed to get manager diagnostics: {e}") return {"error": str(e)} - - def launch_python_shell(self, env_name: Optional[str] = None, cmd: Optional[str] = None) -> bool: + + def launch_python_shell( + self, env_name: Optional[str] = None, cmd: Optional[str] = None + ) -> bool: """Launch a Python shell or execute a command in the environment. - + Args: env_name (str, optional): Environment name. Defaults to current environment. cmd (str, optional): Command to execute. If None, launches interactive shell. Defaults to None. - + Returns: bool: True if successful, False otherwise. - + Raises: HatchEnvironmentError: If no environment name provided and no current environment set. """ if env_name is None: env_name = self.get_current_environment() if not env_name: - raise HatchEnvironmentError("No environment name provided and no current environment set") - + raise HatchEnvironmentError( + "No environment name provided and no current environment set" + ) + if env_name not in self._environments: self.logger.error(f"Environment {env_name} does not exist") return False - + if not self._environments[env_name].get("python_environment", False): self.logger.error(f"No Python environment configured for {env_name}") return False - + try: return self.python_env_manager.launch_shell(env_name, cmd) except PythonEnvironmentError as e: self.logger.error(f"Failed to launch shell for {env_name}: {e}") - return False \ No newline at end of file + return False diff --git a/hatch/installers/__init__.py b/hatch/installers/__init__.py index 3accee5..c45d334 100644 --- a/hatch/installers/__init__.py +++ b/hatch/installers/__init__.py @@ -5,21 +5,21 @@ Python packages, system packages, and Docker containers. """ -from hatch.installers.installer_base import DependencyInstaller, InstallationError, InstallationContext -from hatch.installers.hatch_installer import HatchInstaller -from hatch.installers.python_installer import PythonInstaller -from hatch.installers.system_installer import SystemInstaller -from hatch.installers.docker_installer import DockerInstaller +from hatch.installers.installer_base import ( + DependencyInstaller, + InstallationError, + InstallationContext, +) from hatch.installers.registry import InstallerRegistry, installer_registry __all__ = [ "DependencyInstaller", - "InstallationError", + "InstallationError", "InstallationContext", - #"HatchInstaller", # Not necessary to expose directly, the registry will handle it - #"PythonInstaller", # Not necessary to expose directly, the registry will handle it - #"SystemInstaller", # Not necessary to expose directly, the registry will handle it - #"DockerInstaller", # Not necessary to expose directly, the registry will handle it + # "HatchInstaller", # Not necessary to expose directly, the registry will handle it + # "PythonInstaller", # Not necessary to expose directly, the registry will handle it + # "SystemInstaller", # Not necessary to expose directly, the registry will handle it + # "DockerInstaller", # Not necessary to expose directly, the registry will handle it "InstallerRegistry", - "installer_registry" + "installer_registry", ] diff --git a/hatch/installers/dependency_installation_orchestrator.py b/hatch/installers/dependency_installation_orchestrator.py index e7dfa90..3be72ba 100644 --- a/hatch/installers/dependency_installation_orchestrator.py +++ b/hatch/installers/dependency_installation_orchestrator.py @@ -7,7 +7,6 @@ import json import logging -import datetime import sys import os from pathlib import Path @@ -16,48 +15,52 @@ from hatch_validator.package.package_service import PackageService from hatch_validator.registry.registry_service import RegistryService from hatch_validator.utils.hatch_dependency_graph import HatchDependencyGraphBuilder -from hatch_validator.utils.version_utils import VersionConstraintValidator, VersionConstraintError +from hatch_validator.utils.version_utils import ( + VersionConstraintValidator, + VersionConstraintError, +) from hatch_validator.core.validation_context import ValidationContext from hatch.package_loader import HatchPackageLoader - # Mandatory to insure the installers are registered in the singleton `installer_registry` correctly at import time -from hatch.installers.hatch_installer import HatchInstaller -from hatch.installers.python_installer import PythonInstaller -from hatch.installers.system_installer import SystemInstaller -from hatch.installers.docker_installer import DockerInstaller from hatch.installers.registry import installer_registry from hatch.installers.installer_base import InstallationError -from hatch.installers.installation_context import InstallationContext, InstallationStatus +from hatch.installers.installation_context import ( + InstallationContext, + InstallationStatus, +) class DependencyInstallationError(Exception): """Exception raised for dependency installation-related errors.""" + pass class DependencyInstallerOrchestrator: """Orchestrates dependency installation across all supported dependency types. - + This class coordinates the installation of dependencies by: 1. Resolving all dependencies for a given package using the validator 2. Aggregating installation plans across all dependency types 3. Managing centralized user consent 4. Delegating to appropriate installers via the registry 5. Handling installation order and error recovery - + The orchestrator strictly uses PackageService for all metadata access to ensure compatibility across different package schema versions. """ - def __init__(self, - package_loader: HatchPackageLoader, - registry_service: RegistryService, - registry_data: Dict[str, Any]): + def __init__( + self, + package_loader: HatchPackageLoader, + registry_service: RegistryService, + registry_data: Dict[str, Any], + ): """Initialize the dependency installation orchestrator. - + Args: package_loader (HatchPackageLoader): Package loader for file operations. registry_service (RegistryService): Service for registry operations. @@ -68,10 +71,12 @@ def __init__(self, self.package_loader = package_loader self.registry_service = registry_service self.registry_data = registry_data - + # Python executable configuration for context - self._python_env_vars = Optional[Dict[str, str]] # Environment variables for Python execution - + self._python_env_vars = Optional[ + Dict[str, str] + ] # Environment variables for Python execution + # These will be set during package resolution self.package_service: Optional[PackageService] = None self.dependency_graph_builder: Optional[HatchDependencyGraphBuilder] = None @@ -81,7 +86,7 @@ def __init__(self, def set_python_env_vars(self, python_env_vars: Dict[str, str]) -> None: """Set the environment variables for the Python executable. - + Args: python_env_vars (Dict[str, str]): Environment variables to set for Python execution. """ @@ -95,7 +100,9 @@ def get_python_env_vars(self) -> Optional[Dict[str, str]]: """ return self._python_env_vars - def install_single_dep(self, dep: Dict[str, Any], context: InstallationContext) -> Dict[str, Any]: + def install_single_dep( + self, dep: Dict[str, Any], context: InstallationContext + ) -> Dict[str, Any]: """Install a single dependency into the specified environment context. This method installs a single dependency using the appropriate installer from the registry. @@ -111,7 +118,7 @@ def install_single_dep(self, dep: Dict[str, Any], context: InstallationContext) Returns: Dict[str, Any]: Installed package information containing: - name: Package name - - version: Installed version + - version: Installed version - type: Dependency type - source: Package source URI @@ -125,7 +132,9 @@ def install_single_dep(self, dep: Dict[str, Any], context: InstallationContext) # Check if installer is registered for this dependency type if not installer_registry.is_registered(dep_type): - raise DependencyInstallationError(f"No installer registered for dependency type: {dep_type}") + raise DependencyInstallationError( + f"No installer registered for dependency type: {dep_type}" + ) installer = installer_registry.get_installer(dep_type) @@ -138,36 +147,50 @@ def install_single_dep(self, dep: Dict[str, Any], context: InstallationContext) "name": dep["name"], "version": dep.get("resolved_version", dep.get("version")), "type": dep_type, - "source": dep.get("uri", "unknown") + "source": dep.get("uri", "unknown"), } - self.logger.info(f"Successfully installed {dep_type} dependency: {dep['name']}") + self.logger.info( + f"Successfully installed {dep_type} dependency: {dep['name']}" + ) return installed_package else: - raise DependencyInstallationError(f"Failed to install {dep['name']}: {result.error_message}") + raise DependencyInstallationError( + f"Failed to install {dep['name']}: {result.error_message}" + ) except InstallationError as e: - self.logger.error(f"Installation error for {dep_type} dependency {dep['name']}: {e.error_code}\n{e.message}") - raise DependencyInstallationError(f"Installation error for {dep['name']}: {e}") from e + self.logger.error( + f"Installation error for {dep_type} dependency {dep['name']}: {e.error_code}\n{e.message}" + ) + raise DependencyInstallationError( + f"Installation error for {dep['name']}: {e}" + ) from e except Exception as e: - self.logger.error(f"Error installing {dep_type} dependency {dep['name']}: {e}") - raise DependencyInstallationError(f"Error installing {dep['name']}: {e}") from e - - def install_dependencies(self, - package_path_or_name: str, - env_path: Path, - env_name: str, - existing_packages: Dict[str, str], - version_constraint: Optional[str] = None, - force_download: bool = False, - auto_approve: bool = False) -> Tuple[bool, List[Dict[str, Any]]]: + self.logger.error( + f"Error installing {dep_type} dependency {dep['name']}: {e}" + ) + raise DependencyInstallationError( + f"Error installing {dep['name']}: {e}" + ) from e + + def install_dependencies( + self, + package_path_or_name: str, + env_path: Path, + env_name: str, + existing_packages: Dict[str, str], + version_constraint: Optional[str] = None, + force_download: bool = False, + auto_approve: bool = False, + ) -> Tuple[bool, List[Dict[str, Any]]]: """Install all dependencies for a package with centralized consent management. This method orchestrates the complete dependency installation process by leveraging existing validator components and the installer registry. It handles all dependency types (hatch, python, system, docker) and provides centralized user consent management. - + Args: package_path_or_name (str): Path to local package or name of remote package. env_path (Path): Path to the environment directory. @@ -176,26 +199,35 @@ def install_dependencies(self, version_constraint (str, optional): Version constraint for remote packages. Defaults to None. force_download (bool, optional): Force download even if package is cached. Defaults to False. auto_approve (bool, optional): Skip user consent prompt for automation. Defaults to False. - + Returns: Tuple[bool, List[Dict[str, Any]]]: Success status and list of installed packages. - + Raises: DependencyInstallationError: If installation fails at any stage. """ try: # Step 1: Resolve package and load metadata using PackageService - self._resolve_and_load_package(package_path_or_name, version_constraint, force_download) - + self._resolve_and_load_package( + package_path_or_name, version_constraint, force_download + ) + # Step 2: Get all dependencies organized by type dependencies_by_type = self._get_all_dependencies() - + # Step 3: Filter for missing dependencies by type and track satisfied ones - missing_dependencies_by_type, satisfied_dependencies_by_type = self._filter_missing_dependencies_by_type(dependencies_by_type, existing_packages) - + ( + missing_dependencies_by_type, + satisfied_dependencies_by_type, + ) = self._filter_missing_dependencies_by_type( + dependencies_by_type, existing_packages + ) + # Step 4: Aggregate installation plan - install_plan = self._aggregate_install_plan(missing_dependencies_by_type, satisfied_dependencies_by_type) - + install_plan = self._aggregate_install_plan( + missing_dependencies_by_type, satisfied_dependencies_by_type + ) + # Step 5: Print installation summary for user review self._print_installation_summary(install_plan) @@ -205,69 +237,88 @@ def install_dependencies(self, self.logger.info("Installation cancelled by user") return False, [] else: - self.logger.warning("Auto-approval enabled, proceeding with installation without user consent") - + self.logger.warning( + "Auto-approval enabled, proceeding with installation without user consent" + ) + # Step 7: Execute installation plan using installer registry - installed_packages = self._execute_install_plan(install_plan, env_path, env_name) - + installed_packages = self._execute_install_plan( + install_plan, env_path, env_name + ) + return True, installed_packages - + except Exception as e: self.logger.error(f"Dependency installation failed: {e}") raise DependencyInstallationError(f"Installation failed: {e}") from e - def _resolve_and_load_package(self, - package_path_or_name: str, - version_constraint: Optional[str] = None, - force_download: bool = False) -> None: + def _resolve_and_load_package( + self, + package_path_or_name: str, + version_constraint: Optional[str] = None, + force_download: bool = False, + ) -> None: """Resolve package information and load metadata using PackageService. - + Args: package_path_or_name (str): Path to local package or name of remote package. version_constraint (str, optional): Version constraint for remote packages. force_download (bool, optional): Force download even if package is cached. - + Raises: DependencyInstallationError: If package cannot be resolved or loaded. """ path = Path(package_path_or_name) - + if path.exists() and path.is_dir(): # Local package metadata_path = path / "hatch_metadata.json" if not metadata_path.exists(): - raise DependencyInstallationError(f"Local package missing hatch_metadata.json: {path}") - - with open(metadata_path, 'r') as f: + raise DependencyInstallationError( + f"Local package missing hatch_metadata.json: {path}" + ) + + with open(metadata_path, "r") as f: metadata = json.load(f) - + self._resolved_package_path = path self._resolved_package_type = "local" self._resolved_package_location = str(path.resolve()) - + else: # Remote package if not self.registry_service.package_exists(package_path_or_name): - raise DependencyInstallationError(f"Package {package_path_or_name} does not exist in registry") - + raise DependencyInstallationError( + f"Package {package_path_or_name} does not exist in registry" + ) + try: compatible_version = self.registry_service.find_compatible_version( - package_path_or_name, version_constraint) + package_path_or_name, version_constraint + ) except VersionConstraintError as e: - raise DependencyInstallationError(f"Version constraint error: {e}") from e - - location = self.registry_service.get_package_uri(package_path_or_name, compatible_version) + raise DependencyInstallationError( + f"Version constraint error: {e}" + ) from e + + location = self.registry_service.get_package_uri( + package_path_or_name, compatible_version + ) downloaded_path = self.package_loader.download_package( - location, package_path_or_name, compatible_version, force_download=force_download) - + location, + package_path_or_name, + compatible_version, + force_download=force_download, + ) + metadata_path = downloaded_path / "hatch_metadata.json" - with open(metadata_path, 'r') as f: + with open(metadata_path, "r") as f: metadata = json.load(f) - + self._resolved_package_path = downloaded_path self._resolved_package_type = "remote" self._resolved_package_location = location - + # Load metadata using PackageService for schema-aware access self.package_service = PackageService(metadata) if not self.package_service.is_loaded(): @@ -275,64 +326,68 @@ def _resolve_and_load_package(self, def _get_install_ready_hatch_dependencies(self) -> List[Dict[str, Any]]: """Get install-ready Hatch dependencies using validator components. - + This method only processes Hatch package dependencies, not python, system, or docker. - + Returns: List[Dict[str, Any]]: List of install-ready Hatch dependencies. - + Raises: DependencyInstallationError: If dependency resolution fails. """ try: # Use validator components for Hatch dependency resolution self.dependency_graph_builder = HatchDependencyGraphBuilder( - self.package_service, self.registry_service) - + self.package_service, self.registry_service + ) + context = ValidationContext( package_dir=self._resolved_package_path, registry_data=self.registry_data, - allow_local_dependencies=True + allow_local_dependencies=True, ) - + # This only returns Hatch dependencies in install order - hatch_dependencies = self.dependency_graph_builder.get_install_ready_dependencies(context) + hatch_dependencies = ( + self.dependency_graph_builder.get_install_ready_dependencies(context) + ) return hatch_dependencies - + except Exception as e: - raise DependencyInstallationError(f"Error building Hatch dependency graph: {e}") from e + raise DependencyInstallationError( + f"Error building Hatch dependency graph: {e}" + ) from e def _get_all_dependencies(self) -> Dict[str, List[Dict[str, Any]]]: """Get all dependencies from package metadata organized by type. - + Returns: Dict[str, List[Dict[str, Any]]]: Dependencies organized by type (hatch, python, system, docker). - + Raises: DependencyInstallationError: If dependency extraction fails. """ try: # Get all dependencies using PackageService all_deps = self.package_service.get_dependencies() - + dependencies_by_type = { "system": [], "python": [], "hatch": [], - "docker": [] + "docker": [], } - + # Get Hatch dependencies using validator (properly ordered) dependencies_by_type["hatch"] = self._get_install_ready_hatch_dependencies() # Adding the type information to each Hatch dependency for dep in dependencies_by_type["hatch"]: dep["type"] = "hatch" - + # Get other dependency types directly from PackageService for dep_type in ["python", "system", "docker"]: raw_deps = all_deps.get(dep_type, []) for dep in raw_deps: - # Add type information and ensure required fields dep_with_type = dep.copy() dep_with_type["type"] = dep_type @@ -342,56 +397,64 @@ def _get_all_dependencies(self) -> Dict[str, List[Dict[str, Any]]]: ) dependencies_by_type[dep_type].append(dep_with_type) - + return dependencies_by_type - - except Exception as e: - raise DependencyInstallationError(f"Error extracting dependencies: {e}") from e - def _filter_missing_dependencies_by_type(self, - dependencies_by_type: Dict[str, List[Dict[str, Any]]], - existing_packages: Dict[str, str]) -> Tuple[Dict[str, List[Dict[str, Any]]], Dict[str, List[Dict[str, Any]]]]: + except Exception as e: + raise DependencyInstallationError( + f"Error extracting dependencies: {e}" + ) from e + + def _filter_missing_dependencies_by_type( + self, + dependencies_by_type: Dict[str, List[Dict[str, Any]]], + existing_packages: Dict[str, str], + ) -> Tuple[Dict[str, List[Dict[str, Any]]], Dict[str, List[Dict[str, Any]]]]: """Filter dependencies by type to find those not already installed and track satisfied ones. - - For non-Hatch dependencies, we always include them in missing list as the third-party + + For non-Hatch dependencies, we always include them in missing list as the third-party package manager will handle version checking and installation. - + Args: dependencies_by_type (Dict[str, List[Dict[str, Any]]]): All dependencies organized by type. existing_packages (Dict[str, str]): Currently installed packages {name: version}. - + Returns: - Tuple[Dict[str, List[Dict[str, Any]]], Dict[str, List[Dict[str, Any]]]]: + Tuple[Dict[str, List[Dict[str, Any]]], Dict[str, List[Dict[str, Any]]]]: (missing_dependencies_by_type, satisfied_dependencies_by_type) """ missing_deps_by_type = {} satisfied_deps_by_type = {} - + for dep_type, dependencies in dependencies_by_type.items(): missing_deps = [] satisfied_deps = [] - + for dep in dependencies: dep_name = dep.get("name") - + # For non-Hatch dependencies, always consider them as needing installation # as the third-party package manager will handle version compatibility if dep_type != "hatch": missing_deps.append(dep) continue - + # Hatch dependency processing if dep_name not in existing_packages: missing_deps.append(dep) continue - + # Check version constraints for Hatch dependencies constraint = dep.get("version_constraint") installed_version = existing_packages[dep_name] - + if constraint: - is_compatible, compatibility_msg = VersionConstraintValidator.is_version_compatible( - installed_version, constraint) + ( + is_compatible, + compatibility_msg, + ) = VersionConstraintValidator.is_version_compatible( + installed_version, constraint + ) if not is_compatible: missing_deps.append(dep) else: @@ -404,23 +467,27 @@ def _filter_missing_dependencies_by_type(self, # No constraint specified, any installed version satisfies satisfied_dep = dep.copy() satisfied_dep["installed_version"] = installed_version - satisfied_dep["compatibility_status"] = "No version constraint specified" + satisfied_dep[ + "compatibility_status" + ] = "No version constraint specified" satisfied_deps.append(satisfied_dep) - + missing_deps_by_type[dep_type] = missing_deps satisfied_deps_by_type[dep_type] = satisfied_deps - + return missing_deps_by_type, satisfied_deps_by_type - def _aggregate_install_plan(self, - missing_dependencies_by_type: Dict[str, List[Dict[str, Any]]], - satisfied_dependencies_by_type: Dict[str, List[Dict[str, Any]]]) -> Dict[str, Any]: + def _aggregate_install_plan( + self, + missing_dependencies_by_type: Dict[str, List[Dict[str, Any]]], + satisfied_dependencies_by_type: Dict[str, List[Dict[str, Any]]], + ) -> Dict[str, Any]: """Aggregate installation plan across all dependency types. - + Args: missing_dependencies_by_type (Dict[str, List[Dict[str, Any]]]): Missing dependencies by type. satisfied_dependencies_by_type (Dict[str, List[Dict[str, Any]]]): Already satisfied dependencies by type. - + Returns: Dict[str, Any]: Complete installation plan with dependencies grouped by type. """ @@ -430,52 +497,67 @@ def _aggregate_install_plan(self, "name": self.package_service.get_field("name"), "version": self.package_service.get_field("version"), "type": self._resolved_package_type, - "location": self._resolved_package_location + "location": self._resolved_package_location, }, "dependencies_to_install": missing_dependencies_by_type, "dependencies_satisfied": satisfied_dependencies_by_type, - "total_to_install": 1 + sum(len(deps) for deps in missing_dependencies_by_type.values()), - "total_satisfied": sum(len(deps) for deps in satisfied_dependencies_by_type.values()) + "total_to_install": 1 + + sum(len(deps) for deps in missing_dependencies_by_type.values()), + "total_satisfied": sum( + len(deps) for deps in satisfied_dependencies_by_type.values() + ), } - + return plan - + def _print_installation_summary(self, install_plan: Dict[str, Any]) -> None: """Print a summary of the installation plan for user review. - + Args: install_plan (Dict[str, Any]): Complete installation plan. """ - print("\n" + "="*60) + print("\n" + "=" * 60) print("DEPENDENCY INSTALLATION PLAN") - print("="*60) - - main_pkg = install_plan['main_package'] + print("=" * 60) + + main_pkg = install_plan["main_package"] print(f"Main Package: {main_pkg['name']} v{main_pkg['version']}") print(f"Package Type: {main_pkg['type']}") - + # Show satisfied dependencies first total_satisfied = install_plan.get("total_satisfied", 0) if total_satisfied > 0: print(f"\nDependencies already satisfied: {total_satisfied}") - - for dep_type, deps in install_plan.get("dependencies_satisfied", {}).items(): + + for dep_type, deps in install_plan.get( + "dependencies_satisfied", {} + ).items(): if deps: print(f"\n{dep_type.title()} Dependencies (Satisfied):") for dep in deps: installed_version = dep.get("installed_version", "unknown") constraint = dep.get("version_constraint", "any") compatibility = dep.get("compatibility_status", "") - print(f" βœ“ {dep['name']} {constraint} (installed: {installed_version})") - if compatibility and compatibility != "No version constraint specified": + print( + f" βœ“ {dep['name']} {constraint} (installed: {installed_version})" + ) + if ( + compatibility + and compatibility != "No version constraint specified" + ): print(f" {compatibility}") - + # Show dependencies to install - total_to_install = sum(len(deps) for deps in install_plan.get("dependencies_to_install", {}).values()) + total_to_install = sum( + len(deps) + for deps in install_plan.get("dependencies_to_install", {}).values() + ) if total_to_install > 0: print(f"\nDependencies to install: {total_to_install}") - - for dep_type, deps in install_plan.get("dependencies_to_install", {}).items(): + + for dep_type, deps in install_plan.get( + "dependencies_to_install", {} + ).items(): if deps: print(f"\n{dep_type.title()} Dependencies (To Install):") for dep in deps: @@ -483,11 +565,11 @@ def _print_installation_summary(self, install_plan: Dict[str, Any]) -> None: print(f" β†’ {dep['name']} {constraint}") else: print("\nNo additional dependencies to install.") - + print(f"\nTotal packages to install: {install_plan.get('total_to_install', 1)}") if total_satisfied > 0: print(f"Total dependencies already satisfied: {total_satisfied}") - print("="*60) + print("=" * 60) def _request_user_consent(self, install_plan: Dict[str, Any]) -> bool: """Request user consent for the installation plan with non-TTY support. @@ -499,9 +581,11 @@ def _request_user_consent(self, install_plan: Dict[str, Any]) -> bool: bool: True if user approves, False otherwise. """ # Check for non-interactive mode indicators - if (not sys.stdin.isatty() or - os.getenv('HATCH_AUTO_APPROVE', '').lower() in ('1', 'true', 'yes')): - + if not sys.stdin.isatty() or os.getenv("HATCH_AUTO_APPROVE", "").lower() in ( + "1", + "true", + "yes", + ): self.logger.info("Auto-approving installation (non-interactive mode)") return True @@ -509,9 +593,9 @@ def _request_user_consent(self, install_plan: Dict[str, Any]) -> bool: try: while True: response = input("\nProceed with installation? [y/N]: ").strip().lower() - if response in ['y', 'yes']: + if response in ["y", "yes"]: return True - elif response in ['n', 'no', '']: + elif response in ["n", "no", ""]: return False else: print("Please enter 'y' for yes or 'n' for no.") @@ -519,41 +603,44 @@ def _request_user_consent(self, install_plan: Dict[str, Any]) -> bool: self.logger.info("Installation cancelled by user") return False - def _execute_install_plan(self, - install_plan: Dict[str, Any], - env_path: Path, - env_name: str) -> List[Dict[str, Any]]: + def _execute_install_plan( + self, install_plan: Dict[str, Any], env_path: Path, env_name: str + ) -> List[Dict[str, Any]]: """Execute the installation plan using the installer registry. - + Args: install_plan (Dict[str, Any]): Installation plan to execute. env_path (Path): Environment path for installation. env_name (str): Environment name. - + Returns: List[Dict[str, Any]]: List of successfully installed packages. - + Raises: DependencyInstallationError: If installation fails. """ installed_packages = [] - + # Create comprehensive installation context context = InstallationContext( environment_path=env_path, environment_name=env_name, temp_dir=env_path / ".tmp", - cache_dir=self.package_loader.cache_dir if hasattr(self.package_loader, 'cache_dir') else None, + cache_dir=( + self.package_loader.cache_dir + if hasattr(self.package_loader, "cache_dir") + else None + ), parallel_enabled=False, # Future enhancement - force_reinstall=False, # Future enhancement - simulation_mode=False, # Future enhancement + force_reinstall=False, # Future enhancement + simulation_mode=False, # Future enhancement extra_config={ "package_loader": self.package_loader, "registry_service": self.registry_service, "registry_data": self.registry_data, "main_package_path": self._resolved_package_path, - "main_package_type": self._resolved_package_type - } + "main_package_type": self._resolved_package_type, + }, ) # Configure Python environment variables if available @@ -562,43 +649,50 @@ def _execute_install_plan(self, try: # Install dependencies by type using appropriate installers - for dep_type, dependencies in install_plan["dependencies_to_install"].items(): + for dep_type, dependencies in install_plan[ + "dependencies_to_install" + ].items(): if not dependencies: continue - + if not installer_registry.is_registered(dep_type): - self.logger.warning(f"No installer registered for dependency type: {dep_type}") + self.logger.warning( + f"No installer registered for dependency type: {dep_type}" + ) continue - - installer = installer_registry.get_installer(dep_type) - + + # Verify installer exists (validation only) + installer_registry.get_installer(dep_type) + for dep in dependencies: # Use the extracted install_single_dep method installed_package = self.install_single_dep(dep, context) installed_packages.append(installed_package) - + # Install main package last main_pkg_info = self._install_main_package(context) installed_packages.append(main_pkg_info) - + return installed_packages - + except Exception as e: self.logger.error(f"Installation execution failed: {e}") - raise DependencyInstallationError(f"Installation execution failed: {e}") from e + raise DependencyInstallationError( + f"Installation execution failed: {e}" + ) from e def _install_main_package(self, context: InstallationContext) -> Dict[str, Any]: """Install the main package using package_loader directly. - + The main package installation bypasses the installer registry and uses the package_loader directly since it's not a dependency but the primary package. - + Args: context (InstallationContext): Installation context. - + Returns: Dict[str, Any]: Installed package information. - + Raises: DependencyInstallationError: If main package installation fails. """ @@ -606,31 +700,35 @@ def _install_main_package(self, context: InstallationContext) -> Dict[str, Any]: # Get package information using PackageService package_name = self.package_service.get_field("name") package_version = self.package_service.get_field("version") - + # Install using package_loader directly if self._resolved_package_type == "local": # For local packages, install from resolved path installed_path = self.package_loader.install_local_package( source_path=self._resolved_package_path, target_dir=context.environment_path, - package_name=package_name + package_name=package_name, ) else: # For remote packages, install from downloaded path installed_path = self.package_loader.install_local_package( source_path=self._resolved_package_path, # Downloaded path target_dir=context.environment_path, - package_name=package_name + package_name=package_name, ) - - self.logger.info(f"Successfully installed main package {package_name} to {installed_path}") - + + self.logger.info( + f"Successfully installed main package {package_name} to {installed_path}" + ) + return { "name": package_name, "version": package_version, "type": "hatch", - "source": self._resolved_package_location + "source": self._resolved_package_location, } - + except Exception as e: - raise DependencyInstallationError(f"Failed to install main package: {e}") from e + raise DependencyInstallationError( + f"Failed to install main package: {e}" + ) from e diff --git a/hatch/installers/docker_installer.py b/hatch/installers/docker_installer.py index f3452cd..e3a7da7 100644 --- a/hatch/installers/docker_installer.py +++ b/hatch/installers/docker_installer.py @@ -3,14 +3,21 @@ This module implements installation logic for Docker images using docker-py library, with support for version constraints, registry management, and comprehensive error handling. """ + import logging from pathlib import Path from typing import Dict, Any, Optional, Callable, List from packaging.specifiers import SpecifierSet, InvalidSpecifier -from packaging.version import Version, InvalidVersion +from packaging.version import Version -from .installer_base import DependencyInstaller, InstallationContext, InstallationResult, InstallationError +from .installer_base import ( + DependencyInstaller, + InstallationContext, + InstallationResult, + InstallationError, +) from .installation_context import InstallationStatus +from .registry import installer_registry logger = logging.getLogger("hatch.installers.docker_installer") logger.setLevel(logging.INFO) @@ -18,16 +25,21 @@ # Handle docker-py import with graceful fallback DOCKER_AVAILABLE = False DOCKER_DAEMON_AVAILABLE = False +DOCKER_DAEMON_ERROR = None # Store exception for error reporting try: import docker from docker.errors import DockerException, ImageNotFound, APIError + DOCKER_AVAILABLE = True try: _docker_client = docker.from_env() _docker_client.ping() DOCKER_DAEMON_AVAILABLE = True except DockerException as e: - logger.debug(f"docker-py library is available but Docker daemon is not running or not reachable: {e}") + DOCKER_DAEMON_ERROR = e + logger.debug( + f"docker-py library is available but Docker daemon is not running or not reachable: {e}" + ) except ImportError: docker = None DockerException = Exception @@ -46,7 +58,7 @@ class DockerInstaller(DependencyInstaller): def __init__(self): """Initialize the DockerInstaller. - + Raises: InstallationError: If docker-py library is not available. """ @@ -57,7 +69,7 @@ def __init__(self): @property def installer_type(self) -> str: """Get the installer type identifier. - + Returns: str: The installer type "docker". """ @@ -66,7 +78,7 @@ def installer_type(self) -> str: @property def supported_schemes(self) -> List[str]: """Get the list of supported registry schemes. - + Returns: List[str]: List of supported schemes, currently only ["dockerhub"]. """ @@ -74,65 +86,75 @@ def supported_schemes(self) -> List[str]: def can_install(self, dependency: Dict[str, Any]) -> bool: """Check if this installer can handle the given dependency. - + Args: dependency (Dict[str, Any]): The dependency specification. - + Returns: bool: True if the dependency can be installed, False otherwise. - """ + """ if dependency.get("type") != "docker": return False - + return self._is_docker_available() def validate_dependency(self, dependency: Dict[str, Any]) -> bool: """Validate a Docker dependency specification. - + Args: dependency (Dict[str, Any]): The dependency specification to validate. - + Returns: bool: True if the dependency is valid, False otherwise. """ required_fields = ["name", "version_constraint"] - + # Check required fields if not all(field in dependency for field in required_fields): - logger.error(f"Docker dependency missing required fields. Required: {required_fields}") + logger.error( + f"Docker dependency missing required fields. Required: {required_fields}" + ) return False - + # Validate type if dependency.get("type") != "docker": - logger.error(f"Invalid dependency type: {dependency.get('type')}, expected 'docker'") + logger.error( + f"Invalid dependency type: {dependency.get('type')}, expected 'docker'" + ) return False - + # Validate registry if specified registry = dependency.get("registry", "unknown") if registry not in self.supported_schemes: - logger.error(f"Unsupported registry: {registry}, supported: {self.supported_schemes}") + logger.error( + f"Unsupported registry: {registry}, supported: {self.supported_schemes}" + ) return False - + # Validate version constraint format version_constraint = dependency.get("version_constraint", "") if not self._validate_version_constraint(version_constraint): logger.error(f"Invalid version constraint format: {version_constraint}") return False - + return True - def install(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def install( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Install a Docker image dependency. - + Args: dependency (Dict[str, Any]): The dependency specification. context (InstallationContext): Installation context and configuration. progress_callback (Optional[Callable[[str, float, str], None]]): Progress reporting callback. - + Returns: InstallationResult: Result of the installation operation. - + Raises: InstallationError: If installation fails. """ @@ -141,19 +163,23 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, f"Invalid Docker dependency specification: {dependency}", dependency_name=dependency.get("name", "unknown"), error_code="DOCKER_DEPENDENCY_INVALID", - cause=ValueError("Dependency validation failed") - ) - + cause=ValueError("Dependency validation failed"), + ) + image_name = dependency["name"] version_constraint = dependency["version_constraint"] - registry = dependency.get("registry", "dockerhub") - + # registry = dependency.get("registry", "dockerhub") # Reserved for future use + if progress_callback: - progress_callback(f"Starting Docker image pull: {image_name}", 0.0, "starting") - + progress_callback( + f"Starting Docker image pull: {image_name}", 0.0, "starting" + ) + # Handle simulation mode if context.simulation_mode: - logger.info(f"[SIMULATION] Would pull Docker image: {image_name}:{version_constraint}") + logger.info( + f"[SIMULATION] Would pull Docker image: {image_name}:{version_constraint}" + ) if progress_callback: progress_callback(f"Simulated pull: {image_name}", 100.0, "completed") return InstallationResult( @@ -163,20 +189,20 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, artifacts=[], metadata={ "message": f"Simulated installation of Docker image: {image_name}:{version_constraint}", - } + }, ) - + try: # Resolve version constraint to Docker tag docker_tag = self._resolve_docker_tag(version_constraint) full_image_name = f"{image_name}:{docker_tag}" - + # Pull the Docker image self._pull_docker_image(full_image_name, progress_callback) - + if progress_callback: progress_callback(f"Completed pull: {image_name}", 100.0, "completed") - + return InstallationResult( dependency_name=image_name, status=InstallationStatus.COMPLETED, @@ -184,48 +210,62 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, artifacts=[full_image_name], metadata={ "message": f"Successfully installed Docker image: {full_image_name}", - } + }, ) - + except Exception as e: error_msg = f"Failed to install Docker image {image_name}: {str(e)}" logger.error(error_msg) if progress_callback: progress_callback(f"Failed: {image_name}", 0.0, "error") - raise InstallationError(error_msg, - dependency_name=image_name, - error_code="DOCKER_INSTALL_ERROR", - cause=e) + raise InstallationError( + error_msg, + dependency_name=image_name, + error_code="DOCKER_INSTALL_ERROR", + cause=e, + ) - def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def uninstall( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Uninstall a Docker image dependency. - + Args: dependency (Dict[str, Any]): The dependency specification. context (InstallationContext): Installation context and configuration. progress_callback (Optional[Callable[[str, float, str], None]]): Progress reporting callback. - + Returns: InstallationResult: Result of the uninstallation operation. - + Raises: InstallationError: If uninstallation fails. """ if not self.validate_dependency(dependency): - raise InstallationError(f"Invalid Docker dependency specification: {dependency}") - + raise InstallationError( + f"Invalid Docker dependency specification: {dependency}" + ) + image_name = dependency["name"] version_constraint = dependency["version_constraint"] - + if progress_callback: - progress_callback(f"Starting Docker image removal: {image_name}", 0.0, "starting") - + progress_callback( + f"Starting Docker image removal: {image_name}", 0.0, "starting" + ) + # Handle simulation mode if context.simulation_mode: - logger.info(f"[SIMULATION] Would remove Docker image: {image_name}:{version_constraint}") + logger.info( + f"[SIMULATION] Would remove Docker image: {image_name}:{version_constraint}" + ) if progress_callback: - progress_callback(f"Simulated removal: {image_name}", 100.0, "completed") + progress_callback( + f"Simulated removal: {image_name}", 100.0, "completed" + ) return InstallationResult( dependency_name=image_name, status=InstallationStatus.COMPLETED, @@ -233,20 +273,22 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, artifacts=[], metadata={ "message": f"Simulated removal of Docker image: {image_name}:{version_constraint}", - } + }, ) - + try: # Resolve version constraint to Docker tag docker_tag = self._resolve_docker_tag(version_constraint) full_image_name = f"{image_name}:{docker_tag}" - + # Remove the Docker image self._remove_docker_image(full_image_name, context, progress_callback) - + if progress_callback: - progress_callback(f"Completed removal: {image_name}", 100.0, "completed") - + progress_callback( + f"Completed removal: {image_name}", 100.0, "completed" + ) + return InstallationResult( dependency_name=image_name, status=InstallationStatus.COMPLETED, @@ -254,23 +296,29 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, artifacts=[], metadata={ "message": f"Successfully removed Docker image: {full_image_name}", - } + }, ) - + except Exception as e: error_msg = f"Failed to remove Docker image {image_name}: {str(e)}" logger.error(error_msg) if progress_callback: progress_callback(f"Failed removal: {image_name}", 0.0, "error") - raise InstallationError(error_msg, - dependency_name=image_name, - error_code="DOCKER_UNINSTALL_ERROR", - cause=e) + raise InstallationError( + error_msg, + dependency_name=image_name, + error_code="DOCKER_UNINSTALL_ERROR", + cause=e, + ) - def cleanup_failed_installation(self, dependency: Dict[str, Any], context: InstallationContext, - artifacts: Optional[List[Path]] = None) -> None: + def cleanup_failed_installation( + self, + dependency: Dict[str, Any], + context: InstallationContext, + artifacts: Optional[List[Path]] = None, + ) -> None: """Clean up artifacts from a failed installation. - + Args: dependency (Dict[str, Any]): The dependency that failed to install. context (InstallationContext): Installation context. @@ -278,9 +326,11 @@ def cleanup_failed_installation(self, dependency: Dict[str, Any], context: Insta """ if not artifacts: return - - logger.info(f"Cleaning up failed Docker installation for {dependency.get('name', 'unknown')}") - + + logger.info( + f"Cleaning up failed Docker installation for {dependency.get('name', 'unknown')}" + ) + for artifact in artifacts: if isinstance(artifact, str): # Docker image name try: @@ -295,7 +345,7 @@ def _is_docker_available(self) -> bool: We use the global DOCKER_DAEMON_AVAILABLE flag to determine if Docker is available. It is set to True if the docker-py library is available and the Docker daemon is reachable. - + Returns: bool: True if Docker daemon is available, False otherwise. """ @@ -303,10 +353,10 @@ def _is_docker_available(self) -> bool: def _get_docker_client(self): """Get or create Docker client. - + Returns: docker.DockerClient: Docker client instance. - + Raises: InstallationError: If Docker client cannot be created. """ @@ -314,25 +364,25 @@ def _get_docker_client(self): raise InstallationError( "Docker library not available", error_code="DOCKER_LIBRARY_NOT_AVAILABLE", - cause=ImportError("docker-py library is required for Docker support") - ) - + cause=ImportError("docker-py library is required for Docker support"), + ) + if not DOCKER_DAEMON_AVAILABLE: raise InstallationError( "Docker daemon not available", error_code="DOCKER_DAEMON_NOT_AVAILABLE", - cause=e - ) + cause=DOCKER_DAEMON_ERROR, + ) if self._docker_client is None: self._docker_client = docker.from_env() return self._docker_client def _validate_version_constraint(self, version_constraint: str) -> bool: """Validate version constraint format. - + Args: version_constraint (str): Version constraint to validate. - + Returns: bool: True if valid, False otherwise. """ @@ -344,7 +394,7 @@ def _validate_version_constraint(self, version_constraint: str) -> bool: return True constraint = version_constraint.strip() - + # Accept bare version numbers (e.g. 1.25.0) as valid try: Version(constraint) @@ -362,10 +412,10 @@ def _validate_version_constraint(self, version_constraint: str) -> bool: def _resolve_docker_tag(self, version_constraint: str) -> str: """Resolve version constraint to Docker tag. - + Args: version_constraint (str): Version constraint specification. - + Returns: str: Docker tag to use. """ @@ -373,7 +423,7 @@ def _resolve_docker_tag(self, version_constraint: str) -> str: # Handle simple cases if constraint == "latest": return "latest" - + # Accept bare version numbers as tags try: Version(constraint) @@ -385,147 +435,167 @@ def _resolve_docker_tag(self, version_constraint: str) -> str: try: spec = SpecifierSet(constraint) except InvalidSpecifier: - logger.warning(f"Invalid version constraint '{constraint}', defaulting to 'latest'") + logger.warning( + f"Invalid version constraint '{constraint}', defaulting to 'latest'" + ) return "latest" - - return next(iter(spec)).version # always returns the first matching spec's version - def _pull_docker_image(self, image_name: str, progress_callback: Optional[Callable[[str, float, str], None]]): + return next( + iter(spec) + ).version # always returns the first matching spec's version + + def _pull_docker_image( + self, + image_name: str, + progress_callback: Optional[Callable[[str, float, str], None]], + ): """Pull Docker image with progress reporting. - + Args: image_name (str): Full image name with tag. progress_callback (Optional[Callable[[str, float, str], None]]): Progress callback. - + Raises: InstallationError: If pull fails. """ try: client = self._get_docker_client() - + if progress_callback: progress_callback(f"Pulling {image_name}", 50.0, "pulling") - + # Pull the image client.images.pull(image_name) logger.info(f"Successfully pulled Docker image: {image_name}") - + except ImageNotFound as e: raise InstallationError( f"Docker image not found: {image_name}", error_code="DOCKER_IMAGE_NOT_FOUND", - cause=e - ) + cause=e, + ) except APIError as e: raise InstallationError( f"Docker API error while pulling {image_name}: {e}", error_code="DOCKER_API_ERROR", - cause=e + cause=e, ) except DockerException as e: raise InstallationError( f"Docker error while pulling {image_name}: {e}", error_code="DOCKER_ERROR", - cause=e + cause=e, ) - def _remove_docker_image(self, image_name: str, context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]], - force: bool = False): + def _remove_docker_image( + self, + image_name: str, + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]], + force: bool = False, + ): """Remove Docker image. - + Args: image_name (str): Full image name with tag. context (InstallationContext): Installation context. progress_callback (Optional[Callable[[str, float, str], None]]): Progress callback. force (bool): Whether to force removal even if image is in use. - + Raises: InstallationError: If removal fails. """ try: client = self._get_docker_client() - + if progress_callback: progress_callback(f"Removing {image_name}", 50.0, "removing") - + # Check if image is in use (unless forcing) if not force and self._is_image_in_use(image_name): raise InstallationError( f"Cannot remove Docker image {image_name} as it is in use by running containers", - error_code="DOCKER_IMAGE_IN_USE" + error_code="DOCKER_IMAGE_IN_USE", ) # Remove the image client.images.remove(image_name, force=force) - + logger.info(f"Successfully removed Docker image: {image_name}") - + except ImageNotFound: - logger.warning(f"Docker image not found during removal: {image_name}. Nothing to remove.") + logger.warning( + f"Docker image not found during removal: {image_name}. Nothing to remove." + ) except APIError as e: raise InstallationError( f"Docker API error while removing {image_name}: {e}", error_code="DOCKER_API_ERROR", - cause=e + cause=e, ) except DockerException as e: raise InstallationError( f"Docker error while removing {image_name}: {e}", error_code="DOCKER_ERROR", - cause=e + cause=e, ) def _is_image_in_use(self, image_name: str) -> bool: """Check if Docker image is in use by running containers. - + Args: image_name (str): Image name to check. - + Returns: bool: True if image is in use, False otherwise. """ try: client = self._get_docker_client() containers = client.containers.list(all=True) - + for container in containers: - if container.image.tags and any(tag == image_name for tag in container.image.tags): + if container.image.tags and any( + tag == image_name for tag in container.image.tags + ): return True - + return False - + except Exception as e: - logger.warning(f"Could not check if image {image_name} is in use: {e}\n Assuming NOT in use.") + logger.warning( + f"Could not check if image {image_name} is in use: {e}\n Assuming NOT in use." + ) return False # Assume not in use if we can't check - def get_installation_info(self, dependency: Dict[str, Any], context: InstallationContext) -> Dict[str, Any]: + def get_installation_info( + self, dependency: Dict[str, Any], context: InstallationContext + ) -> Dict[str, Any]: """Get information about Docker image installation. - + Args: dependency (Dict[str, Any]): The dependency specification. context (InstallationContext): Installation context. - + Returns: Dict[str, Any]: Installation information including availability and status. """ image_name = dependency.get("name", "unknown") version_constraint = dependency.get("version_constraint", "latest") - + info = { "installer_type": self.installer_type, "dependency_name": image_name, "version_constraint": version_constraint, "docker_available": self._is_docker_available(), - "can_install": self.can_install(dependency) + "can_install": self.can_install(dependency), } - + if self._is_docker_available(): try: docker_tag = self._resolve_docker_tag(version_constraint) full_image_name = f"{image_name}:{docker_tag}" - + client = self._get_docker_client() try: image = client.images.get(full_image_name) @@ -534,12 +604,12 @@ def get_installation_info(self, dependency: Dict[str, Any], context: Installatio info["image_tags"] = image.tags except ImageNotFound: info["installed"] = False - + except Exception as e: info["error"] = str(e) - + return info + # Register this installer with the global registry -from .registry import installer_registry -installer_registry.register_installer("docker", DockerInstaller) \ No newline at end of file +installer_registry.register_installer("docker", DockerInstaller) diff --git a/hatch/installers/hatch_installer.py b/hatch/installers/hatch_installer.py index 25725b6..85f6d93 100644 --- a/hatch/installers/hatch_installer.py +++ b/hatch/installers/hatch_installer.py @@ -9,10 +9,17 @@ from pathlib import Path from typing import Dict, Any, Optional, Callable, List -from hatch.installers.installer_base import DependencyInstaller, InstallationContext, InstallationResult, InstallationError +from hatch.installers.installer_base import ( + DependencyInstaller, + InstallationContext, + InstallationResult, + InstallationError, +) from hatch.installers.installation_context import InstallationStatus from hatch.package_loader import HatchPackageLoader, PackageLoaderError from hatch_validator.package_validator import HatchPackageValidator +from .registry import installer_registry + class HatchInstaller(DependencyInstaller): """Installer for Hatch package dependencies. @@ -75,8 +82,12 @@ def validate_dependency(self, dependency: Dict[str, Any]) -> bool: # Optionally, perform further validation using the validator if a path is provided return True - def install(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def install( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Install a Hatch package dependency. Args: @@ -94,10 +105,11 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, self.logger.debug(f"Installing Hatch dependency: {dependency}") if not self.validate_dependency(dependency): self.logger.error(f"Invalid dependency format: {dependency}") - raise InstallationError("Invalid dependency object", - dependency_name=dependency.get("name"), - error_code="INVALID_HATCH_DEPENDENCY_FORMAT", - ) + raise InstallationError( + "Invalid dependency object", + dependency_name=dependency.get("name"), + error_code="INVALID_HATCH_DEPENDENCY_FORMAT", + ) name = dependency["name"] version = dependency["resolved_version"] @@ -105,19 +117,27 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, target_dir = Path(context.environment_path) try: if progress_callback: - progress_callback("install", 0.0, f"Installing {name}-{version} from {uri}") + progress_callback( + "install", 0.0, f"Installing {name}-{version} from {uri}" + ) # Download/install the package if uri and uri.startswith("file://"): pkg_path = Path(uri[7:]) - result_path = self.package_loader.install_local_package(pkg_path, target_dir, name) + result_path = self.package_loader.install_local_package( + pkg_path, target_dir, name + ) elif uri: - result_path = self.package_loader.install_remote_package(uri, name, version, target_dir) + result_path = self.package_loader.install_remote_package( + uri, name, version, target_dir + ) else: - raise InstallationError(f"No URI provided for dependency {name}", dependency_name=name) - + raise InstallationError( + f"No URI provided for dependency {name}", dependency_name=name + ) + if progress_callback: progress_callback("install", 1.0, f"Installed {name} to {result_path}") - + return InstallationResult( dependency_name=name, status=InstallationStatus.COMPLETED, @@ -125,15 +145,21 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, installed_version=version, error_message=None, artifacts=result_path, - metadata={"name": name, "version": version} + metadata={"name": name, "version": version}, ) - + except (PackageLoaderError, Exception) as e: self.logger.error(f"Failed to install {name}: {e}") - raise InstallationError(f"Failed to install {name}: {e}", dependency_name=name, cause=e) + raise InstallationError( + f"Failed to install {name}: {e}", dependency_name=name, cause=e + ) - def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def uninstall( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Uninstall a Hatch package dependency. Args: @@ -148,10 +174,11 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, InstallationError: If uninstall fails for any reason. """ if not self.validate_dependency(dependency): - raise InstallationError("Invalid dependency object", - dependency_name=dependency.get("name"), - error_code="INVALID_HATCH_DEPENDENCY_FORMAT", - ) + raise InstallationError( + "Invalid dependency object", + dependency_name=dependency.get("name"), + error_code="INVALID_HATCH_DEPENDENCY_FORMAT", + ) name = dependency["name"] target_dir = Path(context.environment_path) / name @@ -167,14 +194,20 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, installed_version=dependency.get("resolved_version"), error_message=None, artifacts=None, - metadata={"name": name} + metadata={"name": name}, ) except Exception as e: self.logger.error(f"Failed to uninstall {name}: {e}") - raise InstallationError(f"Failed to uninstall {name}: {e}", dependency_name=name, cause=e) + raise InstallationError( + f"Failed to uninstall {name}: {e}", dependency_name=name, cause=e + ) - def cleanup_failed_installation(self, dependency: Dict[str, Any], context: InstallationContext, - artifacts: Optional[List[Path]] = None) -> None: + def cleanup_failed_installation( + self, + dependency: Dict[str, Any], + context: InstallationContext, + artifacts: Optional[List[Path]] = None, + ) -> None: """Clean up artifacts from a failed installation. Args: @@ -193,6 +226,6 @@ def cleanup_failed_installation(self, dependency: Dict[str, Any], context: Insta except Exception: pass + # Register this installer with the global registry -from .registry import installer_registry installer_registry.register_installer("hatch", HatchInstaller) diff --git a/hatch/installers/installation_context.py b/hatch/installers/installation_context.py index 85cccfb..a016583 100644 --- a/hatch/installers/installation_context.py +++ b/hatch/installers/installation_context.py @@ -12,56 +12,57 @@ from dataclasses import dataclass from enum import Enum + @dataclass class InstallationContext: """Context information for dependency installation. - + This class encapsulates all the environment and configuration information needed for installing dependencies, making the installer interface cleaner and more extensible. """ - + environment_path: Path """Path to the target environment where dependencies will be installed.""" - + environment_name: str """Name of the target environment.""" - + temp_dir: Optional[Path] = None """Temporary directory for download/build operations.""" - + cache_dir: Optional[Path] = None """Cache directory for reusable artifacts.""" - + parallel_enabled: bool = True """Whether parallel installation is enabled.""" - + force_reinstall: bool = False """Whether to force reinstallation of existing packages.""" - + simulation_mode: bool = False """Whether to run in simulation mode (no actual installation).""" - + extra_config: Optional[Dict[str, Any]] = None """Additional installer-specific configuration.""" - + def get_config(self, key: str, default: Any = None) -> Any: """Get a configuration value from extra_config. - + Args: key (str): Configuration key to retrieve. default (Any, optional): Default value if key not found. - + Returns: Any: Configuration value or default. """ if self.extra_config is None: return default return self.extra_config.get(key, default) - + def set_config(self, key: str, value: Any) -> None: """Set a configuration value in extra_config. - + Args: key (str): Configuration key to set. value (Any): Value to set for the key. @@ -73,37 +74,39 @@ def set_config(self, key: str, value: Any) -> None: class InstallationStatus(Enum): """Status of an installation operation.""" + PENDING = "pending" IN_PROGRESS = "in_progress" COMPLETED = "completed" FAILED = "failed" ROLLED_BACK = "rolled_back" + @dataclass class InstallationResult: """Result of an installation operation. - + Provides detailed information about the installation outcome, including status, paths, and any error information. """ - + dependency_name: str """Name of the dependency that was installed.""" - + status: InstallationStatus """Final status of the installation.""" - + installed_path: Optional[Path] = None """Path where the dependency was installed.""" - + installed_version: Optional[str] = None """Actual version that was installed.""" - + error_message: Optional[str] = None """Error message if installation failed.""" - + artifacts: Optional[List[Path]] = None """List of files/directories created during installation.""" - + metadata: Optional[Dict[str, Any]] = None - """Additional installer-specific metadata.""" \ No newline at end of file + """Additional installer-specific metadata.""" diff --git a/hatch/installers/installer_base.py b/hatch/installers/installer_base.py index 9792b0d..416a7d2 100644 --- a/hatch/installers/installer_base.py +++ b/hatch/installers/installer_base.py @@ -13,15 +13,20 @@ class InstallationError(Exception): """Exception raised for installation-related errors. - + This exception provides structured error information that can be used for error reporting and recovery strategies. """ - - def __init__(self, message: str, dependency_name: Optional[str] = None, - error_code: Optional[str] = None, cause: Optional[Exception] = None): + + def __init__( + self, + message: str, + dependency_name: Optional[str] = None, + error_code: Optional[str] = None, + cause: Optional[Exception] = None, + ): """Initialize the installation error. - + Args: message (str): Human-readable error message. dependency_name (str, optional): Name of the dependency that failed. @@ -36,11 +41,11 @@ def __init__(self, message: str, dependency_name: Optional[str] = None, class DependencyInstaller(ABC): """Abstract base class for dependency installers. - + This class defines the core interface that all concrete installers must implement. It provides a consistent API for installing and managing dependencies across different types (Hatch packages, Python packages, system packages, Docker containers). - + The installer design follows these principles: - Single responsibility: Each installer handles one dependency type - Extensibility: New dependency types can be added by implementing this interface @@ -48,50 +53,54 @@ class DependencyInstaller(ABC): - Error handling: Structured exceptions and rollback support - Testability: Clear interface for mocking and testing """ - + @property @abstractmethod def installer_type(self) -> str: """Get the type identifier for this installer. - + Returns: str: Unique identifier for the installer type (e.g., "hatch", "python", "docker"). """ pass - + @property @abstractmethod def supported_schemes(self) -> List[str]: """Get the URI schemes this installer can handle. - + Returns: List[str]: List of URI schemes (e.g., ["file", "http", "https"] for local/remote packages). """ pass - + @abstractmethod def can_install(self, dependency: Dict[str, Any]) -> bool: """Check if this installer can handle the given dependency. - + This method allows the installer registry to determine which installer should be used for a specific dependency. - + Args: dependency (Dict[str, Any]): Dependency object with keys like 'type', 'name', 'uri', etc. - + Returns: bool: True if this installer can handle the dependency, False otherwise. """ pass - + @abstractmethod - def install(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def install( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Install a dependency. - + This is the core method that performs the actual installation of a dependency into the specified environment. - + Args: dependency (Dict[str, Any]): Dependency object containing: - name (str): Name of the dependency @@ -103,61 +112,69 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, context (InstallationContext): Installation context with environment info progress_callback (Callable[[str, float, str], None], optional): Progress reporting callback. Parameters: (operation_name, progress_percentage, status_message) - + Returns: InstallationResult: Result of the installation operation. - + Raises: InstallationError: If installation fails for any reason. """ pass - - def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + + def uninstall( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Uninstall a dependency. - + Default implementation raises NotImplementedError. Concrete installers can override this method to provide uninstall functionality. - + Args: dependency (Dict[str, Any]): Dependency object to uninstall. context (InstallationContext): Installation context with environment info. progress_callback (Callable[[str, float, str], None], optional): Progress reporting callback. - + Returns: InstallationResult: Result of the uninstall operation. - + Raises: NotImplementedError: If uninstall is not supported by this installer. InstallationError: If uninstall fails for any reason. """ - raise NotImplementedError(f"Uninstall not implemented for {self.installer_type} installer") - + raise NotImplementedError( + f"Uninstall not implemented for {self.installer_type} installer" + ) + def validate_dependency(self, dependency: Dict[str, Any]) -> bool: """Validate that a dependency object has required fields. - + This method can be overridden by concrete installers to perform installer-specific validation. - + Args: dependency (Dict[str, Any]): Dependency object to validate. - + Returns: bool: True if dependency is valid, False otherwise. """ required_fields = ["name", "version_constraint", "resolved_version"] return all(field in dependency for field in required_fields) - - def get_installation_info(self, dependency: Dict[str, Any], context: InstallationContext) -> Dict[str, Any]: + + def get_installation_info( + self, dependency: Dict[str, Any], context: InstallationContext + ) -> Dict[str, Any]: """Get information about what would be installed without actually installing. - + This method can be used for dry-run scenarios or to provide installation previews to users. - + Args: dependency (Dict[str, Any]): Dependency object to analyze. context (InstallationContext): Installation context. - + Returns: Dict[str, Any]: Information about the planned installation. """ @@ -166,16 +183,20 @@ def get_installation_info(self, dependency: Dict[str, Any], context: Installatio "dependency_name": dependency.get("name"), "resolved_version": dependency.get("resolved_version"), "target_path": str(context.environment_path), - "supported": self.can_install(dependency) + "supported": self.can_install(dependency), } - - def cleanup_failed_installation(self, dependency: Dict[str, Any], context: InstallationContext, - artifacts: Optional[List[Path]] = None) -> None: + + def cleanup_failed_installation( + self, + dependency: Dict[str, Any], + context: InstallationContext, + artifacts: Optional[List[Path]] = None, + ) -> None: """Clean up artifacts from a failed installation. - + This method is called when an installation fails and needs to be rolled back. Concrete installers can override this to perform specific cleanup operations. - + Args: dependency (Dict[str, Any]): Dependency that failed to install. context (InstallationContext): Installation context. @@ -189,6 +210,7 @@ def cleanup_failed_installation(self, dependency: Dict[str, Any], context: Insta artifact.unlink() elif artifact.is_dir(): import shutil + shutil.rmtree(artifact) except Exception: # Log but don't raise - cleanup is best effort diff --git a/hatch/installers/python_installer.py b/hatch/installers/python_installer.py index 40962f6..420471c 100644 --- a/hatch/installers/python_installer.py +++ b/hatch/installers/python_installer.py @@ -9,14 +9,16 @@ import logging import os import json -from pathlib import Path -from typing import Dict, Any, Optional, Callable, List -import os -from pathlib import Path from typing import Dict, Any, Optional, Callable, List -from .installer_base import DependencyInstaller, InstallationContext, InstallationResult, InstallationError +from .installer_base import ( + DependencyInstaller, + InstallationContext, + InstallationResult, + InstallationError, +) from .installation_context import InstallationStatus +from .registry import installer_registry class PythonInstaller(DependencyInstaller): @@ -65,7 +67,7 @@ def can_install(self, dependency: Dict[str, Any]) -> bool: bool: True if this installer can handle the dependency, False otherwise. """ return dependency.get("type") == self.installer_type - + def validate_dependency(self, dependency: Dict[str, Any]) -> bool: """Validate that a dependency object has required fields for Python packages. @@ -78,15 +80,17 @@ def validate_dependency(self, dependency: Dict[str, Any]) -> bool: required_fields = ["name", "version_constraint"] if not all(field in dependency for field in required_fields): return False - + # Check for valid package manager if specified package_manager = dependency.get("package_manager", "pip") if package_manager not in ["pip"]: return False - + return True - def _run_pip_subprocess(self, cmd: List[str], env_vars: Dict[str, str] = None) -> int: + def _run_pip_subprocess( + self, cmd: List[str], env_vars: Dict[str, str] = None + ) -> int: """Run a pip subprocess and return the exit code. Args: @@ -102,33 +106,41 @@ def _run_pip_subprocess(self, cmd: List[str], env_vars: Dict[str, str] = None) - """ env = os.environ.copy() - env['PYTHONUNBUFFERED'] = '1' + env["PYTHONUNBUFFERED"] = "1" env.update(env_vars or {}) # Merge in any additional environment variables - self.logger.debug(f"Running pip command: {' '.join(cmd)} with env: {json.dumps(env, indent=2)}") + self.logger.debug( + f"Running pip command: {' '.join(cmd)} with env: {json.dumps(env, indent=2)}" + ) try: result = subprocess.run( cmd, env=env, check=False, # Don't raise on non-zero exit codes - timeout=300 # 5 minute timeout + timeout=300, # 5 minute timeout ) - + return result.returncode except subprocess.TimeoutExpired: - raise InstallationError("Pip subprocess timed out", error_code="TIMEOUT", cause=None) + raise InstallationError( + "Pip subprocess timed out", error_code="TIMEOUT", cause=None + ) except Exception as e: raise InstallationError( f"Unexpected error running pip command: {e}", error_code="PIP_SUBPROCESS_ERROR", - cause=e + cause=e, ) - def install(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def install( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Install a Python package dependency using pip. This method uses subprocess to call pip with the appropriate Python executable, @@ -147,7 +159,7 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, """ name = dependency["name"] version_constraint = dependency["version_constraint"] - + if progress_callback: progress_callback("validate", 0.0, f"Validating Python package {name}") @@ -156,14 +168,14 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, self.logger.debug(f"Using Python environment variables: {python_env_vars}") python_exec = python_env_vars.get("PYTHON", sys.executable) self.logger.debug(f"Using Python executable: {python_exec}") - + # Build package specification with version constraint # Let pip resolve the actual version based on the constraint if version_constraint and version_constraint != "*": package_spec = f"{name}{version_constraint}" else: package_spec = name - + # Handle extras if specified extras = dependency.get("extras", []) if extras: @@ -177,12 +189,14 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, package_spec = f"{name}[{extras_str}]" # Build pip command - self.logger.debug(f"Installing Python package: {package_spec} using {python_exec}") + self.logger.debug( + f"Installing Python package: {package_spec} using {python_exec}" + ) cmd = [str(python_exec), "-m", "pip", "install", package_spec] - + # Add additional pip options cmd.extend(["--no-cache-dir"]) # Avoid cache issues in different environments - + if context.simulation_mode: # In simulation mode, just return success without actually installing self.logger.info(f"Simulation mode: would install {package_spec}") @@ -190,7 +204,7 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, dependency_name=name, status=InstallationStatus.COMPLETED, installed_version=version_constraint, - metadata={"simulation": True, "command": cmd} + metadata={"simulation": True, "command": cmd}, ) try: @@ -199,42 +213,41 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, returncode = self._run_pip_subprocess(cmd, env_vars=python_env_vars) self.logger.debug(f"pip command: {' '.join(cmd)}\nreturncode: {returncode}") - - if returncode == 0: + if returncode == 0: if progress_callback: progress_callback("install", 1.0, f"Successfully installed {name}") return InstallationResult( dependency_name=name, status=InstallationStatus.COMPLETED, - metadata={ - "command": cmd, - "version_constraint": version_constraint - } + metadata={"command": cmd, "version_constraint": version_constraint}, ) - + else: error_msg = f"Failed to install {name} (exit code: {returncode})" self.logger.error(error_msg) raise InstallationError( - error_msg, - dependency_name=name, - error_code="PIP_FAILED", - cause=None + error_msg, dependency_name=name, error_code="PIP_FAILED", cause=None ) except subprocess.TimeoutExpired: error_msg = f"Installation of {name} timed out after 5 minutes" self.logger.error(error_msg) - raise InstallationError(error_msg, dependency_name=name, error_code="TIMEOUT") - + raise InstallationError( + error_msg, dependency_name=name, error_code="TIMEOUT" + ) + except Exception as e: error_msg = f"Unexpected error installing {name}: {repr(e)}" self.logger.error(error_msg) raise InstallationError(error_msg, dependency_name=name, cause=e) - def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def uninstall( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Uninstall a Python package dependency using pip. Args: @@ -249,7 +262,7 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, InstallationError: If uninstall fails for any reason. """ name = dependency["name"] - + if progress_callback: progress_callback("uninstall", 0.0, f"Uninstalling Python package {name}") @@ -266,7 +279,7 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, return InstallationResult( dependency_name=name, status=InstallationStatus.COMPLETED, - metadata={"simulation": True, "command": cmd} + metadata={"simulation": True, "command": cmd}, ) try: @@ -276,38 +289,41 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, returncode = self._run_pip_subprocess(cmd, env_vars=python_env_vars) if returncode == 0: - if progress_callback: - progress_callback("uninstall", 1.0, f"Successfully uninstalled {name}") + progress_callback( + "uninstall", 1.0, f"Successfully uninstalled {name}" + ) self.logger.info(f"Successfully uninstalled Python package {name}") return InstallationResult( dependency_name=name, status=InstallationStatus.COMPLETED, - metadata={ - "command": cmd - } + metadata={"command": cmd}, ) else: error_msg = f"Failed to uninstall {name} (exit code: {returncode})" self.logger.error(error_msg) - + raise InstallationError( error_msg, dependency_name=name, error_code="PIP_UNINSTALL_FAILED", - cause=None + cause=None, ) except subprocess.TimeoutExpired: error_msg = f"Uninstallation of {name} timed out after 1 minute" self.logger.error(error_msg) - raise InstallationError(error_msg, dependency_name=name, error_code="TIMEOUT") + raise InstallationError( + error_msg, dependency_name=name, error_code="TIMEOUT" + ) except Exception as e: error_msg = f"Unexpected error uninstalling {name}: {e}" self.logger.error(error_msg) raise InstallationError(error_msg, dependency_name=name, cause=e) - - def get_installation_info(self, dependency: Dict[str, Any], context: InstallationContext) -> Dict[str, Any]: + + def get_installation_info( + self, dependency: Dict[str, Any], context: InstallationContext + ) -> Dict[str, Any]: """Get information about what would be installed without actually installing. Args: @@ -319,24 +335,26 @@ def get_installation_info(self, dependency: Dict[str, Any], context: Installatio """ python_exec = context.get_config("python_executable", sys.executable) version_constraint = dependency.get("version_constraint", "*") - + # Build package spec for display if version_constraint and version_constraint != "*": package_spec = f"{dependency['name']}{version_constraint}" else: - package_spec = dependency['name'] - + package_spec = dependency["name"] + info = super().get_installation_info(dependency, context) - info.update({ - "python_executable": str(python_exec), - "package_manager": dependency.get("package_manager", "pip"), - "package_spec": package_spec, - "version_constraint": version_constraint, - "extras": dependency.get("extras", []), - }) - + info.update( + { + "python_executable": str(python_exec), + "package_manager": dependency.get("package_manager", "pip"), + "package_spec": package_spec, + "version_constraint": version_constraint, + "extras": dependency.get("extras", []), + } + ) + return info + # Register this installer with the global registry -from .registry import installer_registry installer_registry.register_installer("python", PythonInstaller) diff --git a/hatch/installers/registry.py b/hatch/installers/registry.py index 574b20c..0e609d0 100644 --- a/hatch/installers/registry.py +++ b/hatch/installers/registry.py @@ -15,11 +15,11 @@ class InstallerRegistry: """Registry for dependency installers by type. - + This class provides a centralized mapping between dependency types and their corresponding installer implementations. It enables the orchestrator to remain agnostic to installer details while providing extensible installer management. - + The registry follows these principles: - Single source of truth for installer-to-type mappings - Dynamic registration and lookup @@ -32,38 +32,46 @@ def __init__(self): self._installers: Dict[str, Type[DependencyInstaller]] = {} logger.debug("Initialized installer registry") - def register_installer(self, dep_type: str, installer_cls: Type[DependencyInstaller]) -> None: + def register_installer( + self, dep_type: str, installer_cls: Type[DependencyInstaller] + ) -> None: """Register an installer class for a dependency type. - + Args: dep_type (str): The dependency type identifier (e.g., "hatch", "python", "docker"). installer_cls (Type[DependencyInstaller]): The installer class to register. - + Raises: ValueError: If the installer class does not implement DependencyInstaller. TypeError: If the installer_cls is not a class or is None. """ if not isinstance(installer_cls, type): raise TypeError(f"installer_cls must be a class, got {type(installer_cls)}") - + if not issubclass(installer_cls, DependencyInstaller): - raise ValueError(f"installer_cls must be a subclass of DependencyInstaller, got {installer_cls}") - + raise ValueError( + f"installer_cls must be a subclass of DependencyInstaller, got {installer_cls}" + ) + if dep_type in self._installers: - logger.warning(f"Overriding existing installer for type '{dep_type}': {self._installers[dep_type]} -> {installer_cls}") - + logger.warning( + f"Overriding existing installer for type '{dep_type}': {self._installers[dep_type]} -> {installer_cls}" + ) + self._installers[dep_type] = installer_cls - logger.debug(f"Registered installer for type '{dep_type}': {installer_cls.__name__}") + logger.debug( + f"Registered installer for type '{dep_type}': {installer_cls.__name__}" + ) def get_installer(self, dep_type: str) -> DependencyInstaller: """Get an installer instance for the given dependency type. - + Args: dep_type (str): The dependency type to get an installer for. - + Returns: DependencyInstaller: A new instance of the appropriate installer. - + Raises: ValueError: If no installer is registered for the given dependency type. """ @@ -73,29 +81,31 @@ def get_installer(self, dep_type: str) -> DependencyInstaller: f"No installer registered for dependency type '{dep_type}'. " f"Available types: {available_types}" ) - + installer_cls = self._installers[dep_type] installer = installer_cls() - logger.debug(f"Created installer instance for type '{dep_type}': {installer_cls.__name__}") + logger.debug( + f"Created installer instance for type '{dep_type}': {installer_cls.__name__}" + ) return installer def can_install(self, dep_type: str, dependency: Dict[str, Any]) -> bool: """Check if the registry can handle the given dependency. - + This method first checks if an installer is registered for the dependency's type, then delegates to the installer's can_install method for more detailed validation. - + Args: dependency (Dict[str, Any]): Dependency object to check. - + Returns: bool: True if the dependency can be installed, False otherwise. """ if dep_type not in self._installers: logger.error(f"No installer registered for dependency type '{dep_type}'") return False - + try: installer = self.get_installer(dep_type) return installer.can_install(dependency) @@ -105,7 +115,7 @@ def can_install(self, dep_type: str, dependency: Dict[str, Any]) -> bool: def get_registered_types(self) -> List[str]: """Get a list of all registered dependency types. - + Returns: List[str]: List of registered dependency type identifiers. """ @@ -113,34 +123,38 @@ def get_registered_types(self) -> List[str]: def is_registered(self, dep_type: str) -> bool: """Check if an installer is registered for the given type. - + Args: dep_type (str): The dependency type to check. - + Returns: bool: True if an installer is registered for the type, False otherwise. """ return dep_type in self._installers - def unregister_installer(self, dep_type: str) -> Optional[Type[DependencyInstaller]]: + def unregister_installer( + self, dep_type: str + ) -> Optional[Type[DependencyInstaller]]: """Unregister an installer for the given dependency type. - + This method is primarily intended for testing and advanced use cases. - + Args: dep_type (str): The dependency type to unregister. - + Returns: Type[DependencyInstaller]: The unregistered installer class, or None if not found. """ installer_cls = self._installers.pop(dep_type, None) if installer_cls: - logger.debug(f"Unregistered installer for type '{dep_type}': {installer_cls.__name__}") + logger.debug( + f"Unregistered installer for type '{dep_type}': {installer_cls.__name__}" + ) return installer_cls def clear(self) -> None: """Clear all registered installers. - + This method is primarily intended for testing purposes. """ self._installers.clear() @@ -148,7 +162,7 @@ def clear(self) -> None: def __len__(self) -> int: """Get the number of registered installers. - + Returns: int: Number of registered installers. """ @@ -156,10 +170,10 @@ def __len__(self) -> int: def __contains__(self, dep_type: str) -> bool: """Check if a dependency type is registered. - + Args: dep_type (str): The dependency type to check. - + Returns: bool: True if the type is registered, False otherwise. """ @@ -167,7 +181,7 @@ def __contains__(self, dep_type: str) -> bool: def __repr__(self) -> str: """Get a string representation of the registry. - + Returns: str: String representation showing registered types. """ diff --git a/hatch/installers/system_installer.py b/hatch/installers/system_installer.py index c95ac78..95820bc 100644 --- a/hatch/installers/system_installer.py +++ b/hatch/installers/system_installer.py @@ -7,15 +7,18 @@ import platform import subprocess import logging -import re import shutil -import os from pathlib import Path from typing import Dict, Any, Optional, Callable, List from packaging.specifiers import SpecifierSet from .installer_base import DependencyInstaller, InstallationError -from .installation_context import InstallationContext, InstallationResult, InstallationStatus +from .installation_context import ( + InstallationContext, + InstallationResult, + InstallationStatus, +) +from .registry import installer_registry class SystemInstaller(DependencyInstaller): @@ -61,11 +64,11 @@ def can_install(self, dependency: Dict[str, Any]) -> bool: """ if dependency.get("type") != self.installer_type: return False - + # Check platform compatibility if not self._is_platform_supported(): return False - + # Check if apt is available return self._is_apt_available() @@ -81,25 +84,35 @@ def validate_dependency(self, dependency: Dict[str, Any]) -> bool: # Required fields per schema required_fields = ["name", "version_constraint"] if not all(field in dependency for field in required_fields): - self.logger.error(f"Missing required fields. Expected: {required_fields}, got: {list(dependency.keys())}") + self.logger.error( + f"Missing required fields. Expected: {required_fields}, got: {list(dependency.keys())}" + ) return False # Validate package manager package_manager = dependency.get("package_manager", "apt") if package_manager != "apt": - self.logger.error(f"Unsupported package manager: {package_manager}. Only 'apt' is supported.") + self.logger.error( + f"Unsupported package manager: {package_manager}. Only 'apt' is supported." + ) return False # Validate version constraint format version_constraint = dependency.get("version_constraint", "") if not self._validate_version_constraint(version_constraint): - self.logger.error(f"Invalid version constraint format: {version_constraint}") + self.logger.error( + f"Invalid version constraint format: {version_constraint}" + ) return False return True - def install(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def install( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Install a system dependency using apt. Args: @@ -120,58 +133,70 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, raise InstallationError( f"Invalid dependency: {dependency}", dependency_name=dependency.get("name"), - error_code="INVALID_DEPENDENCY" + error_code="INVALID_DEPENDENCY", ) package_name = dependency["name"] version_constraint = dependency["version_constraint"] if progress_callback: - progress_callback(f"Installing {package_name}", 0.0, "Starting installation") + progress_callback( + f"Installing {package_name}", 0.0, "Starting installation" + ) - self.logger.info(f"Installing system package: {package_name} with constraint: {version_constraint}") + self.logger.info( + f"Installing system package: {package_name} with constraint: {version_constraint}" + ) try: # Handle dry-run/simulation mode if context.simulation_mode: - return self._simulate_installation(dependency, context, progress_callback) + return self._simulate_installation( + dependency, context, progress_callback + ) # Run apt-get update first update_cmd = ["sudo", "apt-get", "update"] update_returncode = self._run_apt_subprocess(update_cmd) if update_returncode != 0: raise InstallationError( - f"apt-get update failed (see logs for details).", + "apt-get update failed (see logs for details).", dependency_name=package_name, error_code="APT_UPDATE_FAILED", - cause=None + cause=None, ) # Build and execute apt install command cmd = self._build_apt_command(dependency, context) - + if progress_callback: - progress_callback(f"Installing {package_name}", 25.0, "Executing apt command") + progress_callback( + f"Installing {package_name}", 25.0, "Executing apt command" + ) returncode = self._run_apt_subprocess(cmd) self.logger.debug(f"apt command: {cmd}\nreturn code: {returncode}") - + if returncode != 0: raise InstallationError( f"Installation failed for {package_name} (see logs for details).", dependency_name=package_name, error_code="APT_INSTALL_FAILED", - cause=None + cause=None, ) if progress_callback: - progress_callback(f"Installing {package_name}", 75.0, "Verifying installation") + progress_callback( + f"Installing {package_name}", 75.0, "Verifying installation" + ) # Verify installation installed_version = self._verify_installation(package_name) - + if progress_callback: - progress_callback(f"Installing {package_name}", 100.0, "Installation complete") + progress_callback( + f"Installing {package_name}", 100.0, "Installation complete" + ) return InstallationResult( dependency_name=package_name, @@ -182,9 +207,9 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, "command_executed": " ".join(cmd), "platform": platform.platform(), "automated": context.get_config("automated", False), - } + }, ) - + except InstallationError as e: self.logger.error(f"Installation error for {package_name}: {str(e)}") raise e @@ -195,11 +220,15 @@ def install(self, dependency: Dict[str, Any], context: InstallationContext, f"Unexpected error installing {package_name}: {str(e)}", dependency_name=package_name, error_code="UNEXPECTED_ERROR", - cause=e + cause=e, ) - def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def uninstall( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Uninstall a system dependency using apt. Args: @@ -227,13 +256,15 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, # Build apt remove command cmd = ["sudo", "apt", "remove", package_name] - + # Add automation flag if configured if context.get_config("automated", False): cmd.append("-y") - + if progress_callback: - progress_callback(f"Uninstalling {package_name}", 50.0, "Executing apt remove") + progress_callback( + f"Uninstalling {package_name}", 50.0, "Executing apt remove" + ) # Execute command returncode = self._run_apt_subprocess(cmd) @@ -243,11 +274,13 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, f"Uninstallation failed for {package_name} (see logs for details).", dependency_name=package_name, error_code="APT_UNINSTALL_FAILED", - cause=None + cause=None, ) if progress_callback: - progress_callback(f"Uninstalling {package_name}", 100.0, "Uninstall complete") + progress_callback( + f"Uninstalling {package_name}", 100.0, "Uninstall complete" + ) return InstallationResult( dependency_name=package_name, @@ -257,7 +290,7 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, "package_manager": "apt", "command_executed": " ".join(cmd), "automated": context.get_config("automated", False), - } + }, ) except InstallationError as e: self.logger.error(f"Uninstallation error for {package_name}: {str(e)}") @@ -269,7 +302,7 @@ def uninstall(self, dependency: Dict[str, Any], context: InstallationContext, f"Unexpected error uninstalling {package_name}: {str(e)}", dependency_name=package_name, error_code="UNEXPECTED_ERROR", - cause=e + cause=e, ) def _is_platform_supported(self) -> bool: @@ -282,7 +315,7 @@ def _is_platform_supported(self) -> bool: # Check if we're on a Debian-based system if Path("/etc/debian_version").exists(): return True - + # Check platform string system = platform.system().lower() if system == "linux": @@ -291,12 +324,12 @@ def _is_platform_supported(self) -> bool: with open("/etc/os-release", "r") as f: content = f.read().lower() return "ubuntu" in content or "debian" in content - + except FileNotFoundError: pass - + return False - + except Exception: return False @@ -320,16 +353,20 @@ def _validate_version_constraint(self, version_constraint: str) -> bool: try: if not version_constraint.strip(): return True - + SpecifierSet(version_constraint) - + return True - + except Exception: - self.logger.error(f"Invalid version constraint format: {version_constraint}") + self.logger.error( + f"Invalid version constraint format: {version_constraint}" + ) return False - def _build_apt_command(self, dependency: Dict[str, Any], context: InstallationContext) -> List[str]: + def _build_apt_command( + self, dependency: Dict[str, Any], context: InstallationContext + ) -> List[str]: """Build the apt install command for the dependency. Args: @@ -341,14 +378,14 @@ def _build_apt_command(self, dependency: Dict[str, Any], context: InstallationCo """ package_name = dependency["name"] version_constraint = dependency["version_constraint"] - + # Start with base command command = ["sudo", "apt", "install"] # Add automation flag if configured if context.get_config("automated", False): command.append("-y") - + # Handle version constraints # apt doesn't support complex version constraints directly, # but we can specify exact versions for == constraints @@ -359,8 +396,10 @@ def _build_apt_command(self, dependency: Dict[str, Any], context: InstallationCo else: # For other constraints (>=, <=, !=), install latest and let apt handle it package_spec = package_name - self.logger.warning(f"Version constraint {version_constraint} simplified to latest version for {package_name}") - + self.logger.warning( + f"Version constraint {version_constraint} simplified to latest version for {package_name}" + ) + command.append(package_spec) return command @@ -377,14 +416,9 @@ def _run_apt_subprocess(self, cmd: List[str]) -> int: subprocess.TimeoutExpired: If the process times out. InstallationError: For unexpected errors. """ - env = os.environ.copy() + # env = os.environ.copy() # Reserved for future environment customization try: - - process = subprocess.Popen( - cmd, - text=True, - universal_newlines=True - ) + process = subprocess.Popen(cmd, text=True, universal_newlines=True) process.communicate() # Set a timeout for the command process.wait() # Ensure cleanup @@ -393,13 +427,15 @@ def _run_apt_subprocess(self, cmd: List[str]) -> int: except subprocess.TimeoutExpired: process.kill() process.wait() # Ensure cleanup - raise InstallationError("Apt subprocess timed out", error_code="TIMEOUT", cause=None) - + raise InstallationError( + "Apt subprocess timed out", error_code="TIMEOUT", cause=None + ) + except Exception as e: raise InstallationError( f"Unexpected error running apt command: {e}", error_code="APT_SUBPROCESS_ERROR", - cause=e + cause=e, ) def _verify_installation(self, package_name: str) -> Optional[str]: @@ -416,7 +452,7 @@ def _verify_installation(self, package_name: str) -> Optional[str]: ["apt-cache", "policy", package_name], text=True, capture_output=True, - check=False + check=False, ) if result.returncode == 0: for line in result.stdout.splitlines(): @@ -455,8 +491,12 @@ def _parse_apt_error(self, error: InstallationError) -> str: else: return f"Apt command failed: {error_output}" - def _simulate_installation(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def _simulate_installation( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Simulate installation without making actual changes. Args: @@ -468,30 +508,32 @@ def _simulate_installation(self, dependency: Dict[str, Any], context: Installati InstallationResult: Simulated result. """ package_name = dependency["name"] - + if progress_callback: progress_callback(f"Simulating {package_name}", 0.5, "Running dry-run") try: # Use apt's dry-run functionality - need to use apt-get with --dry-run cmd = ["apt-get", "install", "--dry-run", dependency["name"]] - + # Add automation flag if configured if context.get_config("automated", False): cmd.append("-y") - + returncode = self._run_apt_subprocess(cmd) - + if returncode != 0: raise InstallationError( f"Simulation failed for {package_name} (see logs for details).", dependency_name=package_name, error_code="APT_SIMULATION_FAILED", - cause=None + cause=None, ) if progress_callback: - progress_callback(f"Simulating {package_name}", 1.0, "Simulation complete") + progress_callback( + f"Simulating {package_name}", 1.0, "Simulation complete" + ) return InstallationResult( dependency_name=package_name, @@ -501,11 +543,13 @@ def _simulate_installation(self, dependency: Dict[str, Any], context: Installati "command_simulated": " ".join(cmd), "automated": context.get_config("automated", False), "package_manager": "apt", - } + }, ) except InstallationError as e: - self.logger.error(f"Error during installation simulation for {package_name}: {e.message}") + self.logger.error( + f"Error during installation simulation for {package_name}: {e.message}" + ) raise e except Exception as e: @@ -517,12 +561,16 @@ def _simulate_installation(self, dependency: Dict[str, Any], context: Installati "simulation": True, "simulation_error": e, "command_simulated": " ".join(cmd), - "automated": context.get_config("automated", False) - } + "automated": context.get_config("automated", False), + }, ) - def _simulate_uninstall(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback: Optional[Callable[[str, float, str], None]] = None) -> InstallationResult: + def _simulate_uninstall( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback: Optional[Callable[[str, float, str], None]] = None, + ) -> InstallationResult: """Simulate uninstall without making actual changes. Args: @@ -534,25 +582,29 @@ def _simulate_uninstall(self, dependency: Dict[str, Any], context: InstallationC InstallationResult: Simulated result. """ package_name = dependency["name"] - + if progress_callback: - progress_callback(f"Simulating uninstall {package_name}", 0.5, "Running dry-run") + progress_callback( + f"Simulating uninstall {package_name}", 0.5, "Running dry-run" + ) try: # Use apt's dry-run functionality for remove - use apt-get with --dry-run cmd = ["apt-get", "remove", "--dry-run", dependency["name"]] returncode = self._run_apt_subprocess(cmd) - + if returncode != 0: raise InstallationError( f"Uninstall simulation failed for {package_name} (see logs for details).", dependency_name=package_name, error_code="APT_UNINSTALL_SIMULATION_FAILED", - cause=None + cause=None, ) if progress_callback: - progress_callback(f"Simulating uninstall {package_name}", 1.0, "Simulation complete") + progress_callback( + f"Simulating uninstall {package_name}", 1.0, "Simulation complete" + ) return InstallationResult( dependency_name=package_name, @@ -561,12 +613,14 @@ def _simulate_uninstall(self, dependency: Dict[str, Any], context: InstallationC "operation": "uninstall", "simulation": True, "command_simulated": " ".join(cmd), - "automated": context.get_config("automated", False) - } + "automated": context.get_config("automated", False), + }, ) - + except InstallationError as e: - self.logger.error(f"Uninstall simulation error for {package_name}: {str(e)}") + self.logger.error( + f"Uninstall simulation error for {package_name}: {str(e)}" + ) raise e except Exception as e: @@ -579,10 +633,10 @@ def _simulate_uninstall(self, dependency: Dict[str, Any], context: InstallationC "simulation": True, "simulation_error": str(e), "command_simulated": " ".join(cmd), - "automated": context.get_config("automated", False) - } + "automated": context.get_config("automated", False), + }, ) + # Register this installer with the global registry -from .registry import installer_registry installer_registry.register_installer("system", SystemInstaller) diff --git a/hatch/mcp_host_config/__init__.py b/hatch/mcp_host_config/__init__.py index 8f79bcd..3fb3ab7 100644 --- a/hatch/mcp_host_config/__init__.py +++ b/hatch/mcp_host_config/__init__.py @@ -3,38 +3,64 @@ This module provides MCP host configuration management functionality, including backup and restore capabilities for MCP server configurations, decorator-based strategy registration, and consolidated Pydantic models. + +Architecture Notes (v2.0 - Unified Adapter Architecture): +- MCPServerConfig is the single unified model for all MCP configurations +- Host-specific serialization is handled by adapters in hatch/mcp_host_config/adapters/ +- Legacy host-specific models (MCPServerConfigGemini, etc.) have been removed """ from .backup import MCPHostConfigBackupManager from .models import ( - MCPHostType, MCPServerConfig, HostConfiguration, EnvironmentData, - PackageHostConfiguration, EnvironmentPackageEntry, ConfigurationResult, SyncResult, - # Host-specific configuration models - MCPServerConfigBase, MCPServerConfigGemini, MCPServerConfigVSCode, - MCPServerConfigCursor, MCPServerConfigClaude, MCPServerConfigKiro, - MCPServerConfigCodex, MCPServerConfigOmni, - HOST_MODEL_REGISTRY + MCPHostType, + MCPServerConfig, + HostConfiguration, + EnvironmentData, + PackageHostConfiguration, + EnvironmentPackageEntry, + ConfigurationResult, + SyncResult, ) from .host_management import ( - MCPHostRegistry, MCPHostStrategy, MCPHostConfigurationManager, register_host_strategy + MCPHostRegistry, + MCPHostStrategy, + MCPHostConfigurationManager, + register_host_strategy, ) from .reporting import ( - FieldOperation, ConversionReport, generate_conversion_report, display_report + FieldOperation, + ConversionReport, + generate_conversion_report, + display_report, ) +from .adapters import AdapterRegistry, get_adapter, get_default_registry # Import strategies to trigger decorator registration -from . import strategies +from . import strategies # noqa: F401 __all__ = [ - 'MCPHostConfigBackupManager', - 'MCPHostType', 'MCPServerConfig', 'HostConfiguration', 'EnvironmentData', - 'PackageHostConfiguration', 'EnvironmentPackageEntry', 'ConfigurationResult', 'SyncResult', - # Host-specific configuration models - 'MCPServerConfigBase', 'MCPServerConfigGemini', 'MCPServerConfigVSCode', - 'MCPServerConfigCursor', 'MCPServerConfigClaude', 'MCPServerConfigKiro', - 'MCPServerConfigCodex', 'MCPServerConfigOmni', - 'HOST_MODEL_REGISTRY', + "MCPHostConfigBackupManager", + # Core models + "MCPHostType", + "MCPServerConfig", + "HostConfiguration", + "EnvironmentData", + "PackageHostConfiguration", + "EnvironmentPackageEntry", + "ConfigurationResult", + "SyncResult", + # Adapter architecture + "AdapterRegistry", + "get_adapter", + "get_default_registry", # User feedback reporting - 'FieldOperation', 'ConversionReport', 'generate_conversion_report', 'display_report', - 'MCPHostRegistry', 'MCPHostStrategy', 'MCPHostConfigurationManager', 'register_host_strategy' + "FieldOperation", + "ConversionReport", + "generate_conversion_report", + "display_report", + # Host management + "MCPHostRegistry", + "MCPHostStrategy", + "MCPHostConfigurationManager", + "register_host_strategy", ] diff --git a/hatch/mcp_host_config/adapters/__init__.py b/hatch/mcp_host_config/adapters/__init__.py new file mode 100644 index 0000000..a949b0e --- /dev/null +++ b/hatch/mcp_host_config/adapters/__init__.py @@ -0,0 +1,37 @@ +"""MCP Host Config Adapters. + +This module provides host-specific adapters for the Unified Adapter Architecture. +Each adapter handles validation and serialization for a specific MCP host. +""" + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.adapters.claude import ClaudeAdapter +from hatch.mcp_host_config.adapters.codex import CodexAdapter +from hatch.mcp_host_config.adapters.cursor import CursorAdapter +from hatch.mcp_host_config.adapters.gemini import GeminiAdapter +from hatch.mcp_host_config.adapters.kiro import KiroAdapter +from hatch.mcp_host_config.adapters.lmstudio import LMStudioAdapter +from hatch.mcp_host_config.adapters.registry import ( + AdapterRegistry, + get_adapter, + get_default_registry, +) +from hatch.mcp_host_config.adapters.vscode import VSCodeAdapter + +__all__ = [ + # Base classes and exceptions + "AdapterValidationError", + "BaseAdapter", + # Registry + "AdapterRegistry", + "get_adapter", + "get_default_registry", + # Host-specific adapters + "ClaudeAdapter", + "CodexAdapter", + "CursorAdapter", + "GeminiAdapter", + "KiroAdapter", + "LMStudioAdapter", + "VSCodeAdapter", +] diff --git a/hatch/mcp_host_config/adapters/base.py b/hatch/mcp_host_config/adapters/base.py new file mode 100644 index 0000000..5fd0bad --- /dev/null +++ b/hatch/mcp_host_config/adapters/base.py @@ -0,0 +1,266 @@ +"""Base adapter class for MCP host configurations. + +This module defines the abstract BaseAdapter class that all host-specific +adapters must implement. The adapter pattern allows for: +- Host-specific validation rules +- Host-specific serialization format +- Unified interface across all hosts + +Migration Note (v0.8.0): + The adapter architecture has been refactored to follow a validate-after-filter + pattern. Adapters now implement validate_filtered() instead of validate(). + This change fixes cross-host sync failures by ensuring validation only checks + fields that the target host actually supports. + + Old validate() methods are deprecated and will be removed in v0.9.0. +""" + +from abc import ABC, abstractmethod +from typing import Any, Dict, FrozenSet, Optional + +from hatch.mcp_host_config.models import MCPServerConfig +from hatch.mcp_host_config.fields import EXCLUDED_ALWAYS + + +class AdapterValidationError(Exception): + """Raised when adapter validation fails. + + Attributes: + message: Human-readable error message + field: The field that caused the error (if applicable) + host_name: The host adapter that raised the error + """ + + def __init__( + self, message: str, field: Optional[str] = None, host_name: Optional[str] = None + ): + self.message = message + self.field = field + self.host_name = host_name + super().__init__(self._format_message()) + + def _format_message(self) -> str: + """Format the error message with optional context.""" + parts = [] + if self.host_name: + parts.append(f"[{self.host_name}]") + if self.field: + parts.append(f"Field '{self.field}':") + parts.append(self.message) + return " ".join(parts) + + +class BaseAdapter(ABC): + """Abstract base class for host-specific MCP configuration adapters. + + Each host (Claude Desktop, VSCode, Gemini, etc.) has different requirements + for MCP server configuration. Adapters handle: + + 1. **Validation**: Host-specific rules (e.g., "command and url are mutually + exclusive" for Claude, but not for Gemini which supports triple transport) + + 2. **Serialization**: Converting MCPServerConfig to the host's expected format + (field names, structure, excluded fields) + + 3. **Field Support**: Declaring which fields the host supports + + Architecture Pattern (validate-after-filter): + The standard implementation follows: filter β†’ validate β†’ transform + + 1. Filter: Remove unsupported fields (filter_fields) + 2. Validate: Check logical constraints on remaining fields (validate_filtered) + 3. Transform: Apply field mappings if needed (apply_transformations) + + This pattern ensures validation only checks fields the host actually supports, + preventing false rejections during cross-host sync operations. + + Subclasses must implement: + - host_name: The identifier for this host + - get_supported_fields(): Fields this host accepts + - validate_filtered(): Host-specific validation logic (NEW PATTERN) + - serialize(): Convert config to host format + + Subclasses may override: + - apply_transformations(): Field name/value transformations (default: no-op) + - get_excluded_fields(): Additional fields to exclude (default: EXCLUDED_ALWAYS) + + Deprecated methods: + - validate(): Old validation pattern, will be removed in v0.9.0 + Use validate_filtered() instead + + Example (new pattern): + >>> class ClaudeAdapter(BaseAdapter): + ... @property + ... def host_name(self) -> str: + ... return "claude-desktop" + ... + ... def get_supported_fields(self) -> FrozenSet[str]: + ... return frozenset({"command", "args", "env", "url", "headers", "type"}) + ... + ... def validate_filtered(self, filtered: Dict[str, Any]) -> None: + ... # Only validate fields that survived filtering + ... has_command = 'command' in filtered + ... has_url = 'url' in filtered + ... if has_command and has_url: + ... raise AdapterValidationError("Cannot have both command and url") + ... if not has_command and not has_url: + ... raise AdapterValidationError("Must have either command or url") + ... + ... def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + ... filtered = self.filter_fields(config) + ... self.validate_filtered(filtered) + ... return filtered # No transformations needed for Claude + """ + + @property + @abstractmethod + def host_name(self) -> str: + """Return the identifier for this host. + + Returns: + Host identifier string (e.g., "claude-desktop", "vscode", "gemini") + """ + ... + + @abstractmethod + def get_supported_fields(self) -> FrozenSet[str]: + """Return the set of fields supported by this host. + + Returns: + FrozenSet of field names that this host accepts. + Fields not in this set will be filtered during serialization. + """ + ... + + @abstractmethod + def validate(self, config: MCPServerConfig) -> None: + """Validate the configuration for this host. + + This method should check host-specific rules and raise + AdapterValidationError if the configuration is invalid. + + Args: + config: The MCPServerConfig to validate + + Raises: + AdapterValidationError: If validation fails + """ + ... + + @abstractmethod + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate ONLY the fields that survived filtering. + + This method validates logical constraints on filtered fields. + It should NOT check for unsupported fields (already filtered out). + + Validation responsibilities: + - Transport mutual exclusion (command XOR url, or host-specific rules) + - Type consistency (e.g., type='stdio' requires command) + - Business rules (e.g., exactly one transport method) + - Field value constraints (e.g., non-empty strings) + + What NOT to validate: + - Presence of unsupported fields (handled by filter_fields) + - Fields in EXCLUDED_ALWAYS (handled by filter_fields) + + Args: + filtered: Dictionary of filtered fields (only supported, non-excluded, non-None) + + Raises: + AdapterValidationError: If validation fails + + Example: + >>> def validate_filtered(self, filtered: Dict[str, Any]) -> None: + ... # Check transport mutual exclusion + ... has_command = 'command' in filtered + ... has_url = 'url' in filtered + ... if has_command and has_url: + ... raise AdapterValidationError("Cannot have both command and url") + ... if not has_command and not has_url: + ... raise AdapterValidationError("Must have either command or url") + """ + ... + + def apply_transformations(self, filtered: Dict[str, Any]) -> Dict[str, Any]: + """Apply host-specific field transformations. + + This hook method allows adapters to transform field names or values + after filtering and validation. The default implementation is a no-op + (returns filtered unchanged). + + Override this method for hosts that require field mappings, such as: + - Codex: args β†’ arguments, headers β†’ http_headers + - Cross-host sync: includeTools β†’ enabled_tools (Gemini to Codex) + + Args: + filtered: Dictionary of validated, filtered fields + + Returns: + Transformed dictionary ready for serialization + + Example: + >>> def apply_transformations(self, filtered: Dict[str, Any]) -> Dict[str, Any]: + ... result = filtered.copy() + ... if 'args' in result: + ... result['arguments'] = result.pop('args') + ... return result + """ + return filtered + + @abstractmethod + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize the configuration for this host. + + This method should convert the MCPServerConfig to the format + expected by the host's configuration file. + + Standard implementation pattern: + 1. Filter fields: filtered = self.filter_fields(config) + 2. Validate filtered: self.validate_filtered(filtered) + 3. Transform fields: transformed = self.apply_transformations(filtered) + 4. Return transformed + + Args: + config: The MCPServerConfig to serialize + + Returns: + Dictionary in the host's expected format + """ + ... + + def get_excluded_fields(self) -> FrozenSet[str]: + """Return fields that should always be excluded from serialization. + + By default, returns EXCLUDED_ALWAYS (e.g., 'name' which is Hatch metadata). + Subclasses can override to add host-specific exclusions. + + Returns: + FrozenSet of field names to exclude + """ + return EXCLUDED_ALWAYS + + def filter_fields(self, config: MCPServerConfig) -> Dict[str, Any]: + """Filter config to only include supported, non-excluded, non-None fields. + + This is a helper method for serialization that: + 1. Gets all fields from the config + 2. Filters to only supported fields + 3. Removes excluded fields + 4. Removes None values + + Args: + config: The MCPServerConfig to filter + + Returns: + Dictionary with only valid fields for this host + """ + supported = self.get_supported_fields() + excluded = self.get_excluded_fields() + + result = {} + for field, value in config.model_dump(exclude_none=True).items(): + if field in supported and field not in excluded: + result[field] = value + + return result diff --git a/hatch/mcp_host_config/adapters/claude.py b/hatch/mcp_host_config/adapters/claude.py new file mode 100644 index 0000000..9761080 --- /dev/null +++ b/hatch/mcp_host_config/adapters/claude.py @@ -0,0 +1,165 @@ +"""Claude Desktop/Code adapter for MCP host configuration. + +Claude Desktop and Claude Code share the same configuration format: +- Supports 'type' field for transport discrimination +- Mutually exclusive: command XOR url (never both) +- Standard field set: command, args, env, url, headers, type +""" + +from typing import Any, Dict, FrozenSet + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.fields import CLAUDE_FIELDS +from hatch.mcp_host_config.models import MCPServerConfig + + +class ClaudeAdapter(BaseAdapter): + """Adapter for Claude Desktop and Claude Code hosts. + + Claude uses a strict validation model: + - Local servers: command (required), args, env + - Remote servers: url (required), headers, env + - Never both command and url + + Supports the 'type' field for explicit transport discrimination. + """ + + def __init__(self, variant: str = "desktop"): + """Initialize Claude adapter. + + Args: + variant: Either "desktop" or "code" to specify the Claude variant. + """ + if variant not in ("desktop", "code"): + raise ValueError( + f"Invalid Claude variant: {variant}. Must be 'desktop' or 'code'" + ) + self._variant = variant + + @property + def host_name(self) -> str: + """Return the host identifier.""" + return f"claude-{self._variant}" + + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields supported by Claude.""" + return CLAUDE_FIELDS + + def validate(self, config: MCPServerConfig) -> None: + """Validate configuration for Claude. + + DEPRECATED: This method is deprecated and will be removed in v0.9.0. + Use validate_filtered() instead. + + Claude requires exactly one transport: + - stdio (command) + - sse (url) + + Having both command and url is invalid. + """ + has_command = config.command is not None + has_url = config.url is not None + has_http_url = config.httpUrl is not None + + # Claude doesn't support httpUrl + if has_http_url: + raise AdapterValidationError( + "httpUrl is not supported (use 'url' for remote servers)", + field="httpUrl", + host_name=self.host_name, + ) + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # Validate type consistency if specified + if config.type is not None: + if config.type == "stdio" and not has_command: + raise AdapterValidationError( + "type='stdio' requires 'command' field", + field="type", + host_name=self.host_name, + ) + if config.type in ("sse", "http") and not has_url: + raise AdapterValidationError( + f"type='{config.type}' requires 'url' field", + field="type", + host_name=self.host_name, + ) + + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate filtered configuration for Claude. + + Validates only fields that survived filtering (supported by Claude). + Does NOT check for unsupported fields like httpUrl (already filtered). + + Claude requires exactly one transport: + - stdio (command) + - sse (url) + + Args: + filtered: Dictionary of filtered fields + + Raises: + AdapterValidationError: If validation fails + """ + has_command = "command" in filtered + has_url = "url" in filtered + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # Validate type consistency if specified + if "type" in filtered: + config_type = filtered["type"] + if config_type == "stdio" and not has_command: + raise AdapterValidationError( + "type='stdio' requires 'command' field", + field="type", + host_name=self.host_name, + ) + if config_type in ("sse", "http") and not has_url: + raise AdapterValidationError( + f"type='{config_type}' requires 'url' field", + field="type", + host_name=self.host_name, + ) + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize configuration for Claude format. + + Returns a dictionary suitable for Claude's config.json format. + + Follows the validate-after-filter pattern: + 1. Filter to supported fields + 2. Validate filtered fields + 3. Return filtered (no transformations needed) + """ + # Filter to supported fields + filtered = self.filter_fields(config) + + # Validate filtered fields + self.validate_filtered(filtered) + + # Return filtered (no transformations needed for Claude) + return filtered diff --git a/hatch/mcp_host_config/adapters/codex.py b/hatch/mcp_host_config/adapters/codex.py new file mode 100644 index 0000000..0f3f5f9 --- /dev/null +++ b/hatch/mcp_host_config/adapters/codex.py @@ -0,0 +1,149 @@ +"""Codex CLI adapter for MCP host configuration. + +Codex CLI has unique features: +- No 'type' field support +- Field name mappings: argsβ†’arguments, headersβ†’http_headers +- Rich configuration: timeouts, env_vars, tool management, bearer tokens +""" + +from typing import Any, Dict, FrozenSet + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.fields import CODEX_FIELDS, CODEX_FIELD_MAPPINGS +from hatch.mcp_host_config.models import MCPServerConfig + + +class CodexAdapter(BaseAdapter): + """Adapter for Codex CLI MCP host. + + Codex uses different field names than other hosts: + - 'args' β†’ 'arguments' + - 'headers' β†’ 'http_headers' + + Codex also has: + - Working directory support (cwd) + - Timeout configuration (startup_timeout_sec, tool_timeout_sec) + - Server enable/disable (enabled) + - Tool filtering (enabled_tools, disabled_tools) + - Bearer token support (bearer_token_env_var) + """ + + @property + def host_name(self) -> str: + """Return the host identifier.""" + return "codex" + + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields supported by Codex.""" + return CODEX_FIELDS + + def validate(self, config: MCPServerConfig) -> None: + """Validate configuration for Codex. + + DEPRECATED: This method is deprecated and will be removed in v0.9.0. + Use validate_filtered() instead. + + Codex requires exactly one transport (command XOR url). + """ + has_command = config.command is not None + has_url = config.url is not None + has_http_url = config.httpUrl is not None + + # Codex doesn't support httpUrl + if has_http_url: + raise AdapterValidationError( + "httpUrl is not supported (use 'url' for remote servers)", + field="httpUrl", + host_name=self.host_name, + ) + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate filtered configuration for Codex. + + Validates only fields that survived filtering (supported by Codex). + Does NOT check for unsupported fields like httpUrl or type (already filtered). + + Codex requires exactly one transport (command XOR url). + + Args: + filtered: Dictionary of filtered fields + + Raises: + AdapterValidationError: If validation fails + """ + has_command = "command" in filtered + has_url = "url" in filtered + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + def apply_transformations(self, filtered: Dict[str, Any]) -> Dict[str, Any]: + """Apply Codex-specific field transformations. + + Codex uses different field names than the universal schema: + - args β†’ arguments + - headers β†’ http_headers + - includeTools β†’ enabled_tools (for cross-host sync from Gemini) + - excludeTools β†’ disabled_tools (for cross-host sync from Gemini) + + Args: + filtered: Dictionary of validated, filtered fields + + Returns: + Transformed dictionary with Codex field names + """ + result = filtered.copy() + + # Apply field mappings + for universal_name, codex_name in CODEX_FIELD_MAPPINGS.items(): + if universal_name in result: + result[codex_name] = result.pop(universal_name) + + return result + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize configuration for Codex format. + + Follows the validate-after-filter pattern: + 1. Filter to supported fields + 2. Validate filtered fields + 3. Transform fields (apply field mappings) + 4. Return transformed + + Applies field mappings: + - args β†’ arguments + - headers β†’ http_headers + """ + # Filter to supported fields + filtered = self.filter_fields(config) + + # Validate filtered fields + self.validate_filtered(filtered) + + # Transform fields (apply field mappings) + transformed = self.apply_transformations(filtered) + + return transformed diff --git a/hatch/mcp_host_config/adapters/cursor.py b/hatch/mcp_host_config/adapters/cursor.py new file mode 100644 index 0000000..d42a64e --- /dev/null +++ b/hatch/mcp_host_config/adapters/cursor.py @@ -0,0 +1,142 @@ +"""Cursor adapter for MCP host configuration. + +Cursor is similar to VSCode but with limited additional fields: +- envFile: Path to environment file (like VSCode) +- No 'inputs' field support (VSCode only) +""" + +from typing import Any, Dict, FrozenSet + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.fields import CURSOR_FIELDS +from hatch.mcp_host_config.models import MCPServerConfig + + +class CursorAdapter(BaseAdapter): + """Adapter for Cursor MCP host. + + Cursor is like a simplified VSCode: + - Supports Claude base fields + envFile + - Does NOT support inputs (VSCode-only feature) + - Requires exactly one transport (command XOR url) + """ + + @property + def host_name(self) -> str: + """Return the host identifier.""" + return "cursor" + + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields supported by Cursor.""" + return CURSOR_FIELDS + + def validate(self, config: MCPServerConfig) -> None: + """Validate configuration for Cursor. + + DEPRECATED: This method is deprecated and will be removed in v0.9.0. + Use validate_filtered() instead. + + Same rules as Claude: exactly one transport required. + """ + has_command = config.command is not None + has_url = config.url is not None + has_http_url = config.httpUrl is not None + + # Cursor doesn't support httpUrl + if has_http_url: + raise AdapterValidationError( + "httpUrl is not supported (use 'url' for remote servers)", + field="httpUrl", + host_name=self.host_name, + ) + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # Validate type consistency if specified + if config.type is not None: + if config.type == "stdio" and not has_command: + raise AdapterValidationError( + "type='stdio' requires 'command' field", + field="type", + host_name=self.host_name, + ) + if config.type in ("sse", "http") and not has_url: + raise AdapterValidationError( + f"type='{config.type}' requires 'url' field", + field="type", + host_name=self.host_name, + ) + + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate filtered configuration for Cursor. + + Validates only fields that survived filtering (supported by Cursor). + Does NOT check for unsupported fields like httpUrl (already filtered). + + Cursor requires exactly one transport (command XOR url). + + Args: + filtered: Dictionary of filtered fields + + Raises: + AdapterValidationError: If validation fails + """ + has_command = "command" in filtered + has_url = "url" in filtered + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # Validate type consistency if specified + if "type" in filtered: + config_type = filtered["type"] + if config_type == "stdio" and not has_command: + raise AdapterValidationError( + "type='stdio' requires 'command' field", + field="type", + host_name=self.host_name, + ) + if config_type in ("sse", "http") and not has_url: + raise AdapterValidationError( + f"type='{config_type}' requires 'url' field", + field="type", + host_name=self.host_name, + ) + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize configuration for Cursor format. + + Follows the validate-after-filter pattern: + 1. Filter to supported fields + 2. Validate filtered fields + 3. Return filtered (no transformations needed) + """ + # Filter to supported fields + filtered = self.filter_fields(config) + + # Validate filtered fields + self.validate_filtered(filtered) + + # Return filtered (no transformations needed for Cursor) + return filtered diff --git a/hatch/mcp_host_config/adapters/gemini.py b/hatch/mcp_host_config/adapters/gemini.py new file mode 100644 index 0000000..81a54ee --- /dev/null +++ b/hatch/mcp_host_config/adapters/gemini.py @@ -0,0 +1,113 @@ +"""Gemini CLI adapter for MCP host configuration. + +Gemini has unique features: +- Triple transport: command (stdio), url (SSE), httpUrl (HTTP streaming) +- Multiple transports can coexist (not mutually exclusive) +- No 'type' field support +- Rich OAuth configuration +- Working directory, timeout, trust settings +""" + +from typing import Any, Dict, FrozenSet + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.fields import GEMINI_FIELDS +from hatch.mcp_host_config.models import MCPServerConfig + + +class GeminiAdapter(BaseAdapter): + """Adapter for Gemini CLI MCP host. + + Gemini is unique among MCP hosts: + - Supports THREE transport types (stdio, SSE, HTTP streaming) + - Transports are NOT mutually exclusive (can have multiple) + - Does NOT support 'type' field + - Has rich configuration: OAuth, timeout, trust, tool filtering + """ + + @property + def host_name(self) -> str: + """Return the host identifier.""" + return "gemini" + + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields supported by Gemini.""" + return GEMINI_FIELDS + + def validate(self, config: MCPServerConfig) -> None: + """Validate configuration for Gemini. + + DEPRECATED: This method is deprecated and will be removed in v0.9.0. + Use validate_filtered() instead. + + Gemini requires exactly one transport (command, url, or httpUrl). + """ + has_command = config.command is not None + has_url = config.url is not None + has_http_url = config.httpUrl is not None + + # Must have exactly one transport (mutual exclusion) + # Count how many transports are present + transport_count = sum([has_command, has_url, has_http_url]) + + if transport_count == 0: + raise AdapterValidationError( + "At least one transport must be specified: 'command', 'url', or 'httpUrl'", + host_name=self.host_name, + ) + + if transport_count > 1: + raise AdapterValidationError( + "Only one transport allowed: command, url, or httpUrl (not multiple)", + host_name=self.host_name, + ) + + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate filtered configuration for Gemini. + + Validates only fields that survived filtering (supported by Gemini). + Does NOT check for unsupported fields like type (already filtered). + + Gemini requires exactly one transport: command, url, or httpUrl. + + Args: + filtered: Dictionary of filtered fields + + Raises: + AdapterValidationError: If validation fails + """ + has_command = "command" in filtered + has_url = "url" in filtered + has_http_url = "httpUrl" in filtered + + # Must have exactly one transport (mutual exclusion) + transport_count = sum([has_command, has_url, has_http_url]) + + if transport_count == 0: + raise AdapterValidationError( + "At least one transport must be specified: 'command', 'url', or 'httpUrl'", + host_name=self.host_name, + ) + + if transport_count > 1: + raise AdapterValidationError( + "Only one transport allowed: command, url, or httpUrl (not multiple)", + host_name=self.host_name, + ) + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize configuration for Gemini format. + + Follows the validate-after-filter pattern: + 1. Filter to supported fields + 2. Validate filtered fields + 3. Return filtered (no transformations needed) + """ + # Filter to supported fields + filtered = self.filter_fields(config) + + # Validate filtered fields + self.validate_filtered(filtered) + + # Return filtered (no transformations needed for Gemini) + return filtered diff --git a/hatch/mcp_host_config/adapters/kiro.py b/hatch/mcp_host_config/adapters/kiro.py new file mode 100644 index 0000000..c3e11be --- /dev/null +++ b/hatch/mcp_host_config/adapters/kiro.py @@ -0,0 +1,122 @@ +"""Kiro adapter for MCP host configuration. + +Kiro has specific features: +- No 'type' field support +- Server enable/disable via 'disabled' field +- Tool management: autoApprove, disabledTools +""" + +from typing import Any, Dict, FrozenSet + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.fields import KIRO_FIELDS +from hatch.mcp_host_config.models import MCPServerConfig + + +class KiroAdapter(BaseAdapter): + """Adapter for Kiro MCP host. + + Kiro is similar to Claude but without the 'type' field: + - Requires exactly one transport (command XOR url) + - Has 'disabled' field for toggling server + - Has 'autoApprove' for auto-approved tools + - Has 'disabledTools' for disabled tools + """ + + @property + def host_name(self) -> str: + """Return the host identifier.""" + return "kiro" + + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields supported by Kiro.""" + return KIRO_FIELDS + + def validate(self, config: MCPServerConfig) -> None: + """Validate configuration for Kiro. + + DEPRECATED: This method is deprecated and will be removed in v0.9.0. + Use validate_filtered() instead. + + Like Claude, requires exactly one transport. + Does not support 'type' field. + """ + has_command = config.command is not None + has_url = config.url is not None + has_http_url = config.httpUrl is not None + + # Kiro doesn't support httpUrl + if has_http_url: + raise AdapterValidationError( + "httpUrl is not supported (use 'url' for remote servers)", + field="httpUrl", + host_name=self.host_name, + ) + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # 'type' field is not supported by Kiro + if config.type is not None: + raise AdapterValidationError( + "'type' field is not supported by Kiro", + field="type", + host_name=self.host_name, + ) + + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate filtered configuration for Kiro. + + Validates only fields that survived filtering (supported by Kiro). + Does NOT check for unsupported fields like httpUrl or type (already filtered). + + Kiro requires exactly one transport (command XOR url). + + Args: + filtered: Dictionary of filtered fields + + Raises: + AdapterValidationError: If validation fails + """ + has_command = "command" in filtered + has_url = "url" in filtered + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize configuration for Kiro format. + + Follows the validate-after-filter pattern: + 1. Filter to supported fields + 2. Validate filtered fields + 3. Return filtered (no transformations needed) + """ + # Filter to supported fields + filtered = self.filter_fields(config) + + # Validate filtered fields + self.validate_filtered(filtered) + + # Return filtered (no transformations needed for Kiro) + return filtered diff --git a/hatch/mcp_host_config/adapters/lmstudio.py b/hatch/mcp_host_config/adapters/lmstudio.py new file mode 100644 index 0000000..051f55f --- /dev/null +++ b/hatch/mcp_host_config/adapters/lmstudio.py @@ -0,0 +1,139 @@ +"""LM Studio adapter for MCP host configuration. + +LM Studio follows the Cursor/Claude format with the same field set. +""" + +from typing import Any, Dict, FrozenSet + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.fields import LMSTUDIO_FIELDS +from hatch.mcp_host_config.models import MCPServerConfig + + +class LMStudioAdapter(BaseAdapter): + """Adapter for LM Studio MCP host. + + LM Studio uses the same configuration format as Claude/Cursor: + - Supports 'type' field for transport discrimination + - Requires exactly one transport (command XOR url) + """ + + @property + def host_name(self) -> str: + """Return the host identifier.""" + return "lmstudio" + + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields supported by LM Studio.""" + return LMSTUDIO_FIELDS + + def validate(self, config: MCPServerConfig) -> None: + """Validate configuration for LM Studio. + + DEPRECATED: This method is deprecated and will be removed in v0.9.0. + Use validate_filtered() instead. + + Same rules as Claude: exactly one transport required. + """ + has_command = config.command is not None + has_url = config.url is not None + has_http_url = config.httpUrl is not None + + # LM Studio doesn't support httpUrl + if has_http_url: + raise AdapterValidationError( + "httpUrl is not supported (use 'url' for remote servers)", + field="httpUrl", + host_name=self.host_name, + ) + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # Validate type consistency if specified + if config.type is not None: + if config.type == "stdio" and not has_command: + raise AdapterValidationError( + "type='stdio' requires 'command' field", + field="type", + host_name=self.host_name, + ) + if config.type in ("sse", "http") and not has_url: + raise AdapterValidationError( + f"type='{config.type}' requires 'url' field", + field="type", + host_name=self.host_name, + ) + + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate filtered configuration for LM Studio. + + Validates only fields that survived filtering (supported by LM Studio). + Does NOT check for unsupported fields like httpUrl (already filtered). + + LM Studio requires exactly one transport (command XOR url). + + Args: + filtered: Dictionary of filtered fields + + Raises: + AdapterValidationError: If validation fails + """ + has_command = "command" in filtered + has_url = "url" in filtered + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # Validate type consistency if specified + if "type" in filtered: + config_type = filtered["type"] + if config_type == "stdio" and not has_command: + raise AdapterValidationError( + "type='stdio' requires 'command' field", + field="type", + host_name=self.host_name, + ) + if config_type in ("sse", "http") and not has_url: + raise AdapterValidationError( + f"type='{config_type}' requires 'url' field", + field="type", + host_name=self.host_name, + ) + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize configuration for LM Studio format. + + Follows the validate-after-filter pattern: + 1. Filter to supported fields + 2. Validate filtered fields + 3. Return filtered (no transformations needed) + """ + # Filter to supported fields + filtered = self.filter_fields(config) + + # Validate filtered fields + self.validate_filtered(filtered) + + # Return filtered (no transformations needed for LM Studio) + return filtered diff --git a/hatch/mcp_host_config/adapters/registry.py b/hatch/mcp_host_config/adapters/registry.py new file mode 100644 index 0000000..39065b4 --- /dev/null +++ b/hatch/mcp_host_config/adapters/registry.py @@ -0,0 +1,150 @@ +"""Adapter registry for MCP host configurations. + +This module provides a centralized registry for host-specific adapters. +The registry maps host names to adapter instances and provides factory methods. +""" + +from typing import Dict, List, Optional + +from hatch.mcp_host_config.adapters.base import BaseAdapter +from hatch.mcp_host_config.adapters.claude import ClaudeAdapter +from hatch.mcp_host_config.adapters.codex import CodexAdapter +from hatch.mcp_host_config.adapters.cursor import CursorAdapter +from hatch.mcp_host_config.adapters.gemini import GeminiAdapter +from hatch.mcp_host_config.adapters.kiro import KiroAdapter +from hatch.mcp_host_config.adapters.lmstudio import LMStudioAdapter +from hatch.mcp_host_config.adapters.vscode import VSCodeAdapter + + +class AdapterRegistry: + """Registry for MCP host configuration adapters. + + The registry provides: + - Host name to adapter mapping + - Factory method to get adapters by host name + - Registration of custom adapters + - List of all supported hosts + + Example: + >>> registry = AdapterRegistry() + >>> adapter = registry.get_adapter("claude-desktop") + >>> adapter.host_name + 'claude-desktop' + + >>> registry.get_supported_hosts() + ['claude-code', 'claude-desktop', 'codex', 'cursor', 'gemini', 'kiro', 'lmstudio', 'vscode'] + """ + + def __init__(self): + """Initialize the registry with default adapters.""" + self._adapters: Dict[str, BaseAdapter] = {} + self._register_defaults() + + def _register_defaults(self) -> None: + """Register all built-in adapters.""" + # Claude variants + self.register(ClaudeAdapter(variant="desktop")) + self.register(ClaudeAdapter(variant="code")) + + # Other hosts + self.register(VSCodeAdapter()) + self.register(CursorAdapter()) + self.register(LMStudioAdapter()) + self.register(GeminiAdapter()) + self.register(KiroAdapter()) + self.register(CodexAdapter()) + + def register(self, adapter: BaseAdapter) -> None: + """Register an adapter instance. + + Args: + adapter: The adapter instance to register + + Raises: + ValueError: If an adapter with the same host name is already registered + """ + host_name = adapter.host_name + if host_name in self._adapters: + raise ValueError(f"Adapter for '{host_name}' is already registered") + self._adapters[host_name] = adapter + + def get_adapter(self, host_name: str) -> BaseAdapter: + """Get an adapter by host name. + + Args: + host_name: The host identifier (e.g., "claude-desktop", "gemini") + + Returns: + The adapter instance for the specified host + + Raises: + KeyError: If no adapter is registered for the host name + """ + if host_name not in self._adapters: + supported = ", ".join(sorted(self._adapters.keys())) + raise KeyError( + f"No adapter registered for '{host_name}'. Supported hosts: {supported}" + ) + return self._adapters[host_name] + + def has_adapter(self, host_name: str) -> bool: + """Check if an adapter is registered for a host name. + + Args: + host_name: The host identifier to check + + Returns: + True if an adapter is registered, False otherwise + """ + return host_name in self._adapters + + def get_supported_hosts(self) -> List[str]: + """Get a sorted list of all supported host names. + + Returns: + Sorted list of host name strings + """ + return sorted(self._adapters.keys()) + + def unregister(self, host_name: str) -> None: + """Unregister an adapter by host name. + + Args: + host_name: The host identifier to unregister + + Raises: + KeyError: If no adapter is registered for the host name + """ + if host_name not in self._adapters: + raise KeyError(f"No adapter registered for '{host_name}'") + del self._adapters[host_name] + + +# Global registry instance for convenience +_default_registry: Optional[AdapterRegistry] = None + + +def get_default_registry() -> AdapterRegistry: + """Get the default global adapter registry. + + Returns: + The singleton AdapterRegistry instance + """ + global _default_registry + if _default_registry is None: + _default_registry = AdapterRegistry() + return _default_registry + + +def get_adapter(host_name: str) -> BaseAdapter: + """Get an adapter from the default registry. + + This is a convenience function that uses the global registry. + + Args: + host_name: The host identifier (e.g., "claude-desktop", "gemini") + + Returns: + The adapter instance for the specified host + """ + return get_default_registry().get_adapter(host_name) diff --git a/hatch/mcp_host_config/adapters/vscode.py b/hatch/mcp_host_config/adapters/vscode.py new file mode 100644 index 0000000..c309036 --- /dev/null +++ b/hatch/mcp_host_config/adapters/vscode.py @@ -0,0 +1,143 @@ +"""VSCode adapter for MCP host configuration. + +VSCode extends Claude's format with: +- envFile: Path to environment file +- inputs: Input variable definitions (VSCode only) +""" + +from typing import Any, Dict, FrozenSet + +from hatch.mcp_host_config.adapters.base import AdapterValidationError, BaseAdapter +from hatch.mcp_host_config.fields import VSCODE_FIELDS +from hatch.mcp_host_config.models import MCPServerConfig + + +class VSCodeAdapter(BaseAdapter): + """Adapter for Visual Studio Code MCP host. + + VSCode supports the same base configuration as Claude, plus: + - envFile: Path to a .env file for environment variables + - inputs: Array of input variable definitions for prompts + + Like Claude, it requires exactly one transport (command XOR url). + """ + + @property + def host_name(self) -> str: + """Return the host identifier.""" + return "vscode" + + def get_supported_fields(self) -> FrozenSet[str]: + """Return fields supported by VSCode.""" + return VSCODE_FIELDS + + def validate(self, config: MCPServerConfig) -> None: + """Validate configuration for VSCode. + + DEPRECATED: This method is deprecated and will be removed in v0.9.0. + Use validate_filtered() instead. + + Same rules as Claude: exactly one transport required. + """ + has_command = config.command is not None + has_url = config.url is not None + has_http_url = config.httpUrl is not None + + # VSCode doesn't support httpUrl + if has_http_url: + raise AdapterValidationError( + "httpUrl is not supported (use 'url' for remote servers)", + field="httpUrl", + host_name=self.host_name, + ) + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # Validate type consistency if specified + if config.type is not None: + if config.type == "stdio" and not has_command: + raise AdapterValidationError( + "type='stdio' requires 'command' field", + field="type", + host_name=self.host_name, + ) + if config.type in ("sse", "http") and not has_url: + raise AdapterValidationError( + f"type='{config.type}' requires 'url' field", + field="type", + host_name=self.host_name, + ) + + def validate_filtered(self, filtered: Dict[str, Any]) -> None: + """Validate filtered configuration for VSCode. + + Validates only fields that survived filtering (supported by VSCode). + Does NOT check for unsupported fields like httpUrl (already filtered). + + VSCode requires exactly one transport (command XOR url). + + Args: + filtered: Dictionary of filtered fields + + Raises: + AdapterValidationError: If validation fails + """ + has_command = "command" in filtered + has_url = "url" in filtered + + # Must have exactly one transport + if not has_command and not has_url: + raise AdapterValidationError( + "Either 'command' (local) or 'url' (remote) must be specified", + host_name=self.host_name, + ) + + if has_command and has_url: + raise AdapterValidationError( + "Cannot specify both 'command' and 'url' - choose one transport", + host_name=self.host_name, + ) + + # Validate type consistency if specified + if "type" in filtered: + config_type = filtered["type"] + if config_type == "stdio" and not has_command: + raise AdapterValidationError( + "type='stdio' requires 'command' field", + field="type", + host_name=self.host_name, + ) + if config_type in ("sse", "http") and not has_url: + raise AdapterValidationError( + f"type='{config_type}' requires 'url' field", + field="type", + host_name=self.host_name, + ) + + def serialize(self, config: MCPServerConfig) -> Dict[str, Any]: + """Serialize configuration for VSCode format. + + Follows the validate-after-filter pattern: + 1. Filter to supported fields + 2. Validate filtered fields + 3. Return filtered (no transformations needed) + """ + # Filter to supported fields + filtered = self.filter_fields(config) + + # Validate filtered fields + self.validate_filtered(filtered) + + # Return filtered (no transformations needed for VSCode) + return filtered diff --git a/hatch/mcp_host_config/backup.py b/hatch/mcp_host_config/backup.py index 7e1ca75..26ab840 100644 --- a/hatch/mcp_host_config/backup.py +++ b/hatch/mcp_host_config/backup.py @@ -6,7 +6,6 @@ import json import shutil -import tempfile from datetime import datetime from pathlib import Path from typing import Dict, List, Optional, Any, Callable, TextIO @@ -16,89 +15,98 @@ class BackupError(Exception): """Exception raised when backup operations fail.""" + pass class RestoreError(Exception): """Exception raised when restore operations fail.""" + pass class BackupInfo(BaseModel): """Information about a backup file with validation.""" + hostname: str = Field(..., description="Host identifier") timestamp: datetime = Field(..., description="Backup creation timestamp") file_path: Path = Field(..., description="Path to backup file") file_size: int = Field(..., ge=0, description="Backup file size in bytes") - original_config_path: Path = Field(..., description="Original configuration file path") - - @validator('hostname') + original_config_path: Path = Field( + ..., description="Original configuration file path" + ) + + @validator("hostname") def validate_hostname(cls, v): """Validate hostname is supported.""" supported_hosts = { - 'claude-desktop', 'claude-code', 'vscode', - 'cursor', 'lmstudio', 'gemini', 'kiro', 'codex' + "claude-desktop", + "claude-code", + "vscode", + "cursor", + "lmstudio", + "gemini", + "kiro", + "codex", } if v not in supported_hosts: raise ValueError(f"Unsupported hostname: {v}. Supported: {supported_hosts}") return v - - @validator('file_path') + + @validator("file_path") def validate_file_exists(cls, v): """Validate backup file exists.""" if not v.exists(): raise ValueError(f"Backup file does not exist: {v}") return v - + @property def backup_name(self) -> str: """Get backup filename.""" # Extract original filename from backup path if available # Backup filename format: {original_name}.{hostname}.{timestamp} return self.file_path.name - + @property def age_days(self) -> int: """Get backup age in days.""" return (datetime.now() - self.timestamp).days - + class Config: """Pydantic configuration.""" + arbitrary_types_allowed = True - json_encoders = { - Path: str, - datetime: lambda v: v.isoformat() - } + json_encoders = {Path: str, datetime: lambda v: v.isoformat()} class BackupResult(BaseModel): """Result of backup operation with validation.""" + success: bool = Field(..., description="Operation success status") backup_path: Optional[Path] = Field(None, description="Path to created backup") error_message: Optional[str] = Field(None, description="Error message if failed") original_size: int = Field(0, ge=0, description="Original file size in bytes") backup_size: int = Field(0, ge=0, description="Backup file size in bytes") - - @validator('backup_path') + + @validator("backup_path") def validate_backup_path_on_success(cls, v, values): """Validate backup_path is provided when success is True.""" - if values.get('success') and v is None: + if values.get("success") and v is None: raise ValueError("backup_path must be provided when success is True") return v - - @validator('error_message') + + @validator("error_message") def validate_error_message_on_failure(cls, v, values): """Validate error_message is provided when success is False.""" - if not values.get('success') and not v: + if not values.get("success") and not v: raise ValueError("error_message must be provided when success is False") return v - + class Config: """Pydantic configuration.""" + arbitrary_types_allowed = True - json_encoders = { - Path: str - } + json_encoders = {Path: str} class AtomicFileOperations: @@ -111,7 +119,7 @@ def atomic_write_with_serializer( serializer: Callable[[Any, TextIO], None], backup_manager: "MCPHostConfigBackupManager", hostname: str, - skip_backup: bool = False + skip_backup: bool = False, ) -> bool: """Atomic write with custom serializer and automatic backup creation. @@ -134,12 +142,14 @@ def atomic_write_with_serializer( if file_path.exists() and not skip_backup: backup_result = backup_manager.create_backup(file_path, hostname) if not backup_result.success: - raise BackupError(f"Required backup failed: {backup_result.error_message}") + raise BackupError( + f"Required backup failed: {backup_result.error_message}" + ) temp_file = None try: temp_file = file_path.with_suffix(f"{file_path.suffix}.tmp") - with open(temp_file, 'w', encoding='utf-8') as f: + with open(temp_file, "w", encoding="utf-8") as f: serializer(data, f) temp_file.replace(file_path) @@ -151,15 +161,22 @@ def atomic_write_with_serializer( if backup_result and backup_result.backup_path: try: - backup_manager.restore_backup(hostname, backup_result.backup_path.name) + backup_manager.restore_backup( + hostname, backup_result.backup_path.name + ) except Exception: pass raise BackupError(f"Atomic write failed: {str(e)}") - def atomic_write_with_backup(self, file_path: Path, data: Dict[str, Any], - backup_manager: "MCPHostConfigBackupManager", - hostname: str, skip_backup: bool = False) -> bool: + def atomic_write_with_backup( + self, + file_path: Path, + data: Dict[str, Any], + backup_manager: "MCPHostConfigBackupManager", + hostname: str, + skip_backup: bool = False, + ) -> bool: """Atomic write with JSON serialization (backward compatible). Args: @@ -175,34 +192,35 @@ def atomic_write_with_backup(self, file_path: Path, data: Dict[str, Any], Raises: BackupError: If backup creation fails and skip_backup is False """ + def json_serializer(data: Any, f: TextIO) -> None: json.dump(data, f, indent=2, ensure_ascii=False) return self.atomic_write_with_serializer( file_path, data, json_serializer, backup_manager, hostname, skip_backup ) - + def atomic_copy(self, source: Path, target: Path) -> bool: """Atomic file copy operation. - + Args: source (Path): Source file path target (Path): Target file path - + Returns: bool: True if copy successful, False otherwise """ try: # Create temporary target file temp_target = target.with_suffix(f"{target.suffix}.tmp") - + # Copy to temporary location shutil.copy2(source, temp_target) - + # Atomic move to final location temp_target.replace(target) return True - + except Exception: # Clean up temporary file on failure temp_target = target.with_suffix(f"{target.suffix}.tmp") @@ -213,25 +231,27 @@ def atomic_copy(self, source: Path, target: Path) -> bool: class MCPHostConfigBackupManager: """Manages MCP host configuration backups.""" - + def __init__(self, backup_root: Optional[Path] = None): """Initialize backup manager. - + Args: - backup_root (Path, optional): Root directory for backups. + backup_root (Path, optional): Root directory for backups. Defaults to ~/.hatch/mcp_host_config_backups/ """ - self.backup_root = backup_root or Path.home() / ".hatch" / "mcp_host_config_backups" + self.backup_root = ( + backup_root or Path.home() / ".hatch" / "mcp_host_config_backups" + ) self.backup_root.mkdir(parents=True, exist_ok=True) self.atomic_ops = AtomicFileOperations() - + def create_backup(self, config_path: Path, hostname: str) -> BackupResult: """Create timestamped backup of host configuration. - + Args: config_path (Path): Path to original configuration file hostname (str): Host identifier (claude-desktop, claude-code, vscode, cursor, lmstudio, gemini) - + Returns: BackupResult: Operation result with backup path or error message """ @@ -240,61 +260,55 @@ def create_backup(self, config_path: Path, hostname: str) -> BackupResult: if not config_path.exists(): return BackupResult( success=False, - error_message=f"Configuration file not found: {config_path}" + error_message=f"Configuration file not found: {config_path}", ) - + # Validate hostname using Pydantic try: BackupInfo.validate_hostname(hostname) except ValueError as e: - return BackupResult( - success=False, - error_message=str(e) - ) - + return BackupResult(success=False, error_message=str(e)) + # Create host-specific backup directory host_backup_dir = self.backup_root / hostname host_backup_dir.mkdir(exist_ok=True) - + # Generate timestamped backup filename with microseconds for uniqueness # Preserve original filename instead of hardcoding 'mcp.json' timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f") original_filename = config_path.name backup_name = f"{original_filename}.{hostname}.{timestamp}" backup_path = host_backup_dir / backup_name - + # Get original file size original_size = config_path.stat().st_size - + # Atomic copy operation if not self.atomic_ops.atomic_copy(config_path, backup_path): return BackupResult( - success=False, - error_message="Atomic copy operation failed" + success=False, error_message="Atomic copy operation failed" ) - + # Verify backup integrity backup_size = backup_path.stat().st_size if backup_size != original_size: backup_path.unlink() return BackupResult( - success=False, - error_message="Backup size mismatch - backup deleted" + success=False, error_message="Backup size mismatch - backup deleted" ) - + return BackupResult( success=True, backup_path=backup_path, original_size=original_size, - backup_size=backup_size + backup_size=backup_size, ) - + except Exception as e: return BackupResult( - success=False, - error_message=f"Backup creation failed: {str(e)}" + success=False, error_message=f"Backup creation failed: {str(e)}" ) - + def restore_backup(self, hostname: str, backup_file: Optional[str] = None) -> bool: """Restore configuration from backup. @@ -338,34 +352,36 @@ def restore_backup(self, hostname: str, backup_file: Optional[str] = None) -> bo except Exception: return False - + def list_backups(self, hostname: str) -> List[BackupInfo]: """List available backups for hostname. - + Args: hostname (str): Host identifier - + Returns: List[BackupInfo]: List of backup information objects """ host_backup_dir = self.backup_root / hostname - + if not host_backup_dir.exists(): return [] - + backups = [] - # Search for both correct format and legacy incorrect format for backward compatibility + # Search for backups with flexible filename matching + # Different hosts use different config filenames (mcp.json, settings.json, config.toml) + # Backup format: {original_filename}.{hostname}.{timestamp} patterns = [ - f"mcp.json.{hostname}.*", # Correct format: mcp.json.gemini.* - f"mcp.json.MCPHostType.{hostname.upper()}.*" # Legacy incorrect format: mcp.json.MCPHostType.GEMINI.* + f"*.{hostname}.*", # Flexible: settings.json.gemini.*, mcp.json.claude-desktop.*, etc. + f"mcp.json.MCPHostType.{hostname.upper()}.*", # Legacy incorrect format for backward compatibility ] for pattern in patterns: for backup_file in host_backup_dir.glob(pattern): try: # Parse timestamp from filename - timestamp_str = backup_file.name.split('.')[-1] + timestamp_str = backup_file.name.split(".")[-1] timestamp = datetime.strptime(timestamp_str, "%Y%m%d_%H%M%S_%f") backup_info = BackupInfo( @@ -373,34 +389,36 @@ def list_backups(self, hostname: str) -> List[BackupInfo]: timestamp=timestamp, file_path=backup_file, file_size=backup_file.stat().st_size, - original_config_path=Path("placeholder") # Will be implemented in host config phase + original_config_path=Path( + "placeholder" + ), # Will be implemented in host config phase ) backups.append(backup_info) except (ValueError, OSError): # Skip invalid backup files continue - + # Sort by timestamp (newest first) return sorted(backups, key=lambda b: b.timestamp, reverse=True) - + def clean_backups(self, hostname: str, **filters) -> int: """Clean old backups based on filters. - + Args: hostname (str): Host identifier **filters: Filter criteria (e.g., older_than_days, keep_count) - + Returns: int: Number of backups cleaned """ backups = self.list_backups(hostname) cleaned_count = 0 - + # Apply filters - older_than_days = filters.get('older_than_days') - keep_count = filters.get('keep_count') - + older_than_days = filters.get("older_than_days") + keep_count = filters.get("keep_count") + if older_than_days: for backup in backups: if backup.age_days > older_than_days: @@ -409,7 +427,7 @@ def clean_backups(self, hostname: str, **filters) -> int: cleaned_count += 1 except OSError: continue - + if keep_count and len(backups) > keep_count: # Keep newest backups, remove oldest to_remove = backups[keep_count:] @@ -419,15 +437,15 @@ def clean_backups(self, hostname: str, **filters) -> int: cleaned_count += 1 except OSError: continue - + return cleaned_count - + def _get_latest_backup(self, hostname: str) -> Optional[Path]: """Get path to latest backup for hostname. - + Args: hostname (str): Host identifier - + Returns: Optional[Path]: Path to latest backup or None if no backups exist """ @@ -437,48 +455,50 @@ def _get_latest_backup(self, hostname: str) -> Optional[Path]: class BackupAwareOperation: """Base class for operations that require backup awareness.""" - + def __init__(self, backup_manager: MCPHostConfigBackupManager): """Initialize backup-aware operation. - + Args: backup_manager (MCPHostConfigBackupManager): Backup manager instance """ self.backup_manager = backup_manager - - def prepare_backup(self, config_path: Path, hostname: str, - no_backup: bool = False) -> Optional[BackupResult]: + + def prepare_backup( + self, config_path: Path, hostname: str, no_backup: bool = False + ) -> Optional[BackupResult]: """Prepare backup before operation if required. - + Args: config_path (Path): Path to configuration file hostname (str): Host identifier no_backup (bool, optional): Skip backup creation. Defaults to False. - + Returns: Optional[BackupResult]: BackupResult if backup created, None if skipped - + Raises: BackupError: If backup required but fails """ if no_backup: return None - + backup_result = self.backup_manager.create_backup(config_path, hostname) if not backup_result.success: raise BackupError(f"Required backup failed: {backup_result.error_message}") - + return backup_result - - def rollback_on_failure(self, backup_result: Optional[BackupResult], - config_path: Path, hostname: str) -> bool: + + def rollback_on_failure( + self, backup_result: Optional[BackupResult], config_path: Path, hostname: str + ) -> bool: """Rollback configuration on operation failure. - + Args: backup_result (Optional[BackupResult]): Result from prepare_backup config_path (Path): Path to configuration file hostname (str): Host identifier - + Returns: bool: True if rollback successful, False otherwise """ diff --git a/hatch/mcp_host_config/fields.py b/hatch/mcp_host_config/fields.py new file mode 100644 index 0000000..2531cd0 --- /dev/null +++ b/hatch/mcp_host_config/fields.py @@ -0,0 +1,141 @@ +""" +Field constants for MCP host configuration adapter architecture. + +This module defines the source of truth for field support across MCP hosts. +All adapters reference these constants to determine field filtering and mapping. +""" + +from typing import FrozenSet + +# ============================================================================ +# Universal Fields (supported by ALL hosts) +# ============================================================================ + +UNIVERSAL_FIELDS: FrozenSet[str] = frozenset( + { + "command", # Executable path/name for local servers + "args", # Command arguments for local servers + "env", # Environment variables (all transports) + "url", # Server endpoint URL for remote servers (SSE transport) + "headers", # HTTP headers for remote servers + } +) + + +# ============================================================================ +# Type Field Support +# ============================================================================ + +# Hosts that support the 'type' discriminator field (stdio/sse/http) +# Note: Gemini, Kiro, Codex do NOT support this field +TYPE_SUPPORTING_HOSTS: FrozenSet[str] = frozenset( + { + "claude-desktop", + "claude-code", + "vscode", + "cursor", + } +) + + +# ============================================================================ +# Host-Specific Field Sets +# ============================================================================ + +# Fields supported by Claude Desktop/Code (universal + type) +CLAUDE_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset( + { + "type", # Transport discriminator + } +) + +# Fields supported by VSCode (Claude fields + envFile + inputs) +VSCODE_FIELDS: FrozenSet[str] = CLAUDE_FIELDS | frozenset( + { + "envFile", # Path to environment file + "inputs", # Input variable definitions (VSCode only) + } +) + +# Fields supported by Cursor (Claude fields + envFile, no inputs) +CURSOR_FIELDS: FrozenSet[str] = CLAUDE_FIELDS | frozenset( + { + "envFile", # Path to environment file + } +) + +# Fields supported by LMStudio (universal + type) +LMSTUDIO_FIELDS: FrozenSet[str] = CLAUDE_FIELDS + +# Fields supported by Gemini (no type field, but has httpUrl and others) +GEMINI_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset( + { + "httpUrl", # HTTP streaming endpoint URL + "timeout", # Request timeout in milliseconds + "trust", # Bypass tool call confirmations + "cwd", # Working directory for stdio transport + "includeTools", # Tools to include (allowlist) + "excludeTools", # Tools to exclude (blocklist) + # OAuth configuration + "oauth_enabled", + "oauth_clientId", + "oauth_clientSecret", + "oauth_authorizationUrl", + "oauth_tokenUrl", + "oauth_scopes", + "oauth_redirectUri", + "oauth_tokenParamName", + "oauth_audiences", + "authProviderType", + } +) + +# Fields supported by Kiro (no type field) +KIRO_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset( + { + "disabled", # Whether server is disabled + "autoApprove", # Auto-approved tool names + "disabledTools", # Disabled tool names + } +) + +# Fields supported by Codex (no type field, has field mappings) +CODEX_FIELDS: FrozenSet[str] = UNIVERSAL_FIELDS | frozenset( + { + "cwd", # Working directory + "env_vars", # Environment variables to whitelist/forward + "startup_timeout_sec", # Server startup timeout + "tool_timeout_sec", # Tool execution timeout + "enabled", # Enable/disable server + "enabled_tools", # Allow-list of tools + "disabled_tools", # Deny-list of tools + "bearer_token_env_var", # Env var containing bearer token + "http_headers", # HTTP headers (Codex naming) + "env_http_headers", # Header names to env var names mapping + } +) + + +# ============================================================================ +# Field Mappings (universal name β†’ host-specific name) +# ============================================================================ + +# Codex uses different field names for some universal/shared fields +CODEX_FIELD_MAPPINGS: dict[str, str] = { + "args": "arguments", # Codex uses 'arguments' instead of 'args' + "headers": "http_headers", # Codex uses 'http_headers' instead of 'headers' + "includeTools": "enabled_tools", # Gemini naming β†’ Codex naming + "excludeTools": "disabled_tools", # Gemini naming β†’ Codex naming +} + + +# ============================================================================ +# Metadata Fields (never serialized to host config files) +# ============================================================================ + +# Fields that are Hatch metadata and should NEVER appear in serialized output +EXCLUDED_ALWAYS: FrozenSet[str] = frozenset( + { + "name", # Server name is key in the config dict, not a field value + } +) diff --git a/hatch/mcp_host_config/host_management.py b/hatch/mcp_host_config/host_management.py index 56c8b5b..d4177f0 100644 --- a/hatch/mcp_host_config/host_management.py +++ b/hatch/mcp_host_config/host_management.py @@ -8,12 +8,15 @@ from typing import Dict, List, Type, Optional, Callable, Any from pathlib import Path -import json import logging from .models import ( - MCPHostType, MCPServerConfig, HostConfiguration, EnvironmentData, - ConfigurationResult, SyncResult + MCPHostType, + MCPServerConfig, + HostConfiguration, + EnvironmentData, + ConfigurationResult, + SyncResult, ) logger = logging.getLogger(__name__) @@ -21,41 +24,51 @@ class MCPHostRegistry: """Registry for MCP host strategies with decorator-based registration.""" - + _strategies: Dict[MCPHostType, Type["MCPHostStrategy"]] = {} _instances: Dict[MCPHostType, "MCPHostStrategy"] = {} _family_mappings: Dict[str, List[MCPHostType]] = { "claude": [MCPHostType.CLAUDE_DESKTOP, MCPHostType.CLAUDE_CODE], - "cursor": [MCPHostType.CURSOR, MCPHostType.LMSTUDIO] + "cursor": [MCPHostType.CURSOR, MCPHostType.LMSTUDIO], } - + @classmethod def register(cls, host_type: MCPHostType): """Decorator to register a host strategy class.""" + def decorator(strategy_class: Type["MCPHostStrategy"]): if not issubclass(strategy_class, MCPHostStrategy): - raise ValueError(f"Strategy class {strategy_class.__name__} must inherit from MCPHostStrategy") - + raise ValueError( + f"Strategy class {strategy_class.__name__} must inherit from MCPHostStrategy" + ) + if host_type in cls._strategies: - logger.warning(f"Overriding existing strategy for {host_type}: {cls._strategies[host_type].__name__} -> {strategy_class.__name__}") - + logger.warning( + f"Overriding existing strategy for {host_type}: {cls._strategies[host_type].__name__} -> {strategy_class.__name__}" + ) + cls._strategies[host_type] = strategy_class - logger.debug(f"Registered MCP host strategy '{host_type}' -> {strategy_class.__name__}") + logger.debug( + f"Registered MCP host strategy '{host_type}' -> {strategy_class.__name__}" + ) return strategy_class + return decorator - + @classmethod def get_strategy(cls, host_type: MCPHostType) -> "MCPHostStrategy": """Get strategy instance for host type.""" if host_type not in cls._strategies: available = list(cls._strategies.keys()) - raise ValueError(f"Unknown host type: '{host_type}'. Available: {available}") - + raise ValueError( + f"Unknown host type: '{host_type}'. Available: {available}" + ) + if host_type not in cls._instances: cls._instances[host_type] = cls._strategies[host_type]() - + return cls._instances[host_type] - + @classmethod def detect_available_hosts(cls) -> List[MCPHostType]: """Detect available hosts on the system.""" @@ -69,12 +82,12 @@ def detect_available_hosts(cls) -> List[MCPHostType]: # Host detection failed, skip continue return available_hosts - + @classmethod def get_family_hosts(cls, family: str) -> List[MCPHostType]: """Get all hosts in a strategy family.""" return cls._family_mappings.get(family, []) - + @classmethod def get_host_config_path(cls, host_type: MCPHostType) -> Optional[Path]: """Get configuration path for host type.""" @@ -89,28 +102,29 @@ def register_host_strategy(host_type: MCPHostType) -> Callable: class MCPHostStrategy: """Abstract base class for host configuration strategies.""" - + def get_config_path(self) -> Optional[Path]: """Get configuration file path for this host.""" raise NotImplementedError("Subclasses must implement get_config_path") - + def is_host_available(self) -> bool: """Check if host is available on system.""" raise NotImplementedError("Subclasses must implement is_host_available") - + def read_configuration(self) -> HostConfiguration: """Read and parse host configuration.""" raise NotImplementedError("Subclasses must implement read_configuration") - - def write_configuration(self, config: HostConfiguration, - no_backup: bool = False) -> bool: + + def write_configuration( + self, config: HostConfiguration, no_backup: bool = False + ) -> bool: """Write configuration to host file.""" raise NotImplementedError("Subclasses must implement write_configuration") - + def validate_server_config(self, server_config: MCPServerConfig) -> bool: """Validate server configuration for this host.""" raise NotImplementedError("Subclasses must implement validate_server_config") - + def get_config_key(self) -> str: """Get the root configuration key for MCP servers.""" return "mcpServers" # Default for most platforms @@ -118,70 +132,74 @@ def get_config_key(self) -> str: class MCPHostConfigurationManager: """Central manager for MCP host configuration operations.""" - + def __init__(self, backup_manager: Optional[Any] = None): self.host_registry = MCPHostRegistry self.backup_manager = backup_manager or self._create_default_backup_manager() - + def _create_default_backup_manager(self): """Create default backup manager.""" try: from .backup import MCPHostConfigBackupManager + return MCPHostConfigBackupManager() except ImportError: logger.warning("Backup manager not available") return None - - def configure_server(self, server_config: MCPServerConfig, - hostname: str, no_backup: bool = False) -> ConfigurationResult: + + def configure_server( + self, server_config: MCPServerConfig, hostname: str, no_backup: bool = False + ) -> ConfigurationResult: """Configure MCP server on specified host.""" try: host_type = MCPHostType(hostname) strategy = self.host_registry.get_strategy(host_type) - + # Validate server configuration for this host if not strategy.validate_server_config(server_config): return ConfigurationResult( success=False, hostname=hostname, - error_message=f"Server configuration invalid for {hostname}" + error_message=f"Server configuration invalid for {hostname}", ) - + # Read current configuration current_config = strategy.read_configuration() - + # Create backup if requested backup_path = None if not no_backup and self.backup_manager: config_path = strategy.get_config_path() if config_path and config_path.exists(): - backup_result = self.backup_manager.create_backup(config_path, hostname) + backup_result = self.backup_manager.create_backup( + config_path, hostname + ) if backup_result.success: backup_path = backup_result.backup_path - + # Add server to configuration - server_name = getattr(server_config, 'name', 'default_server') + server_name = getattr(server_config, "name", "default_server") current_config.add_server(server_name, server_config) - + # Write updated configuration success = strategy.write_configuration(current_config, no_backup=no_backup) - + return ConfigurationResult( success=success, hostname=hostname, server_name=server_name, backup_created=backup_path is not None, - backup_path=backup_path + backup_path=backup_path, ) - + except Exception as e: return ConfigurationResult( - success=False, - hostname=hostname, - error_message=str(e) + success=False, hostname=hostname, error_message=str(e) ) - def get_server_config(self, hostname: str, server_name: str) -> Optional[MCPServerConfig]: + def get_server_config( + self, hostname: str, server_name: str + ) -> Optional[MCPServerConfig]: """ Get existing server configuration from host. @@ -202,74 +220,84 @@ def get_server_config(self, hostname: str, server_name: str) -> Optional[MCPServ return None except Exception as e: - logger.debug(f"Failed to retrieve server config for {server_name} on {hostname}: {e}") + logger.debug( + f"Failed to retrieve server config for {server_name} on {hostname}: {e}" + ) return None - def remove_server(self, server_name: str, hostname: str, - no_backup: bool = False) -> ConfigurationResult: + def remove_server( + self, server_name: str, hostname: str, no_backup: bool = False + ) -> ConfigurationResult: """Remove MCP server from specified host.""" try: host_type = MCPHostType(hostname) strategy = self.host_registry.get_strategy(host_type) - + # Read current configuration current_config = strategy.read_configuration() - + # Check if server exists if server_name not in current_config.servers: return ConfigurationResult( success=False, hostname=hostname, server_name=server_name, - error_message=f"Server '{server_name}' not found in {hostname} configuration" + error_message=f"Server '{server_name}' not found in {hostname} configuration", ) - + # Create backup if requested backup_path = None if not no_backup and self.backup_manager: config_path = strategy.get_config_path() if config_path and config_path.exists(): - backup_result = self.backup_manager.create_backup(config_path, hostname) + backup_result = self.backup_manager.create_backup( + config_path, hostname + ) if backup_result.success: backup_path = backup_result.backup_path - + # Remove server from configuration current_config.remove_server(server_name) - + # Write updated configuration success = strategy.write_configuration(current_config, no_backup=no_backup) - + return ConfigurationResult( success=success, hostname=hostname, server_name=server_name, backup_created=backup_path is not None, - backup_path=backup_path + backup_path=backup_path, ) - + except Exception as e: return ConfigurationResult( success=False, hostname=hostname, server_name=server_name, - error_message=str(e) + error_message=str(e), ) - - def sync_environment_to_hosts(self, env_data: EnvironmentData, - target_hosts: Optional[List[str]] = None, - no_backup: bool = False) -> SyncResult: + + def sync_environment_to_hosts( + self, + env_data: EnvironmentData, + target_hosts: Optional[List[str]] = None, + no_backup: bool = False, + ) -> SyncResult: """Synchronize environment MCP data to host configurations.""" if target_hosts is None: - target_hosts = [host.value for host in self.host_registry.detect_available_hosts()] - + target_hosts = [ + host.value for host in self.host_registry.detect_available_hosts() + ] + results = [] servers_synced = 0 - + for hostname in target_hosts: try: host_type = MCPHostType(hostname) strategy = self.host_registry.get_strategy(host_type) - + # Collect all MCP servers for this host from environment host_servers = {} for package in env_data.get_mcp_packages(): @@ -277,62 +305,72 @@ def sync_environment_to_hosts(self, env_data: EnvironmentData, host_config = package.configured_hosts[hostname] # Use package name as server name (single server per package) host_servers[package.name] = host_config.server_config - + if not host_servers: # No servers to sync for this host - results.append(ConfigurationResult( - success=True, - hostname=hostname, - error_message="No servers to sync" - )) + results.append( + ConfigurationResult( + success=True, + hostname=hostname, + error_message="No servers to sync", + ) + ) continue - + # Read current host configuration current_config = strategy.read_configuration() - + # Create backup if requested backup_path = None if not no_backup and self.backup_manager: config_path = strategy.get_config_path() if config_path and config_path.exists(): - backup_result = self.backup_manager.create_backup(config_path, hostname) + backup_result = self.backup_manager.create_backup( + config_path, hostname + ) if backup_result.success: backup_path = backup_result.backup_path - + # Update configuration with environment servers for server_name, server_config in host_servers.items(): current_config.add_server(server_name, server_config) servers_synced += 1 - + # Write updated configuration - success = strategy.write_configuration(current_config, no_backup=no_backup) - - results.append(ConfigurationResult( - success=success, - hostname=hostname, - backup_created=backup_path is not None, - backup_path=backup_path - )) - + success = strategy.write_configuration( + current_config, no_backup=no_backup + ) + + results.append( + ConfigurationResult( + success=success, + hostname=hostname, + backup_created=backup_path is not None, + backup_path=backup_path, + ) + ) + except Exception as e: - results.append(ConfigurationResult( - success=False, - hostname=hostname, - error_message=str(e) - )) - + results.append( + ConfigurationResult( + success=False, hostname=hostname, error_message=str(e) + ) + ) + # Calculate summary statistics successful_results = [r for r in results if r.success] hosts_updated = len(successful_results) - + return SyncResult( success=hosts_updated > 0, results=results, servers_synced=servers_synced, - hosts_updated=hosts_updated + hosts_updated=hosts_updated, ) - def remove_host_configuration(self, hostname: str, no_backup: bool = False) -> ConfigurationResult: + def remove_host_configuration( + self, hostname: str, no_backup: bool = False + ) -> ConfigurationResult: """Remove entire host configuration (all MCP servers). Args: @@ -351,7 +389,7 @@ def remove_host_configuration(self, hostname: str, no_backup: bool = False) -> C return ConfigurationResult( success=True, hostname=hostname, - error_message="No configuration file to remove" + error_message="No configuration file to remove", ) # Create backup if requested @@ -370,23 +408,101 @@ def remove_host_configuration(self, hostname: str, no_backup: bool = False) -> C success=True, hostname=hostname, backup_created=backup_path is not None, - backup_path=backup_path + backup_path=backup_path, ) except Exception as e: return ConfigurationResult( - success=False, - hostname=hostname, - error_message=str(e) + success=False, hostname=hostname, error_message=str(e) ) - def sync_configurations(self, - from_env: Optional[str] = None, - from_host: Optional[str] = None, - to_hosts: Optional[List[str]] = None, - servers: Optional[List[str]] = None, - pattern: Optional[str] = None, - no_backup: bool = False) -> SyncResult: + def preview_sync( + self, + from_env: Optional[str] = None, + from_host: Optional[str] = None, + servers: Optional[List[str]] = None, + pattern: Optional[str] = None, + ) -> List[str]: + """Preview which servers would be synced without performing actual sync. + + Reuses the source resolution and filtering logic from sync_configurations() + to return the list of server names that match the given source and filters. + + Args: + from_env: Source environment name. + from_host: Source host name. + servers: Specific server names to filter by. + pattern: Regex pattern for server name selection. + + Returns: + List[str]: Server names matching the source and filters. + + Raises: + ValueError: If source specification is invalid. + """ + import re + from hatch.environment_manager import HatchEnvironmentManager + + if not from_env and not from_host: + raise ValueError("Must specify either from_env or from_host as source") + if from_env and from_host: + raise ValueError("Cannot specify both from_env and from_host as source") + + try: + # Resolve source data + if from_env: + env_manager = HatchEnvironmentManager() + env_data = env_manager.get_environment_data(from_env) + if not env_data: + return [] + + source_servers = {} + for package in env_data.get_mcp_packages(): + source_servers[package.name] = package.configured_hosts + else: + try: + host_type = MCPHostType(from_host) + strategy = self.host_registry.get_strategy(host_type) + host_config = strategy.read_configuration() + + source_servers = {} + for server_name, server_config in host_config.servers.items(): + source_servers[server_name] = { + from_host: {"server_config": server_config} + } + except ValueError: + return [] + + # Apply server filtering + if servers: + source_servers = { + name: config + for name, config in source_servers.items() + if name in servers + } + elif pattern: + regex = re.compile(pattern) + source_servers = { + name: config + for name, config in source_servers.items() + if regex.match(name) + } + + return sorted(source_servers.keys()) + + except Exception: + return [] + + def sync_configurations( + self, + from_env: Optional[str] = None, + from_host: Optional[str] = None, + to_hosts: Optional[List[str]] = None, + servers: Optional[List[str]] = None, + pattern: Optional[str] = None, + no_backup: bool = False, + generate_reports: bool = False, + ) -> SyncResult: """Advanced synchronization with multiple source/target options. Args: @@ -396,6 +512,7 @@ def sync_configurations(self, servers (List[str], optional): Specific server names to sync pattern (str, optional): Regex pattern for server selection no_backup (bool, optional): Skip backup creation. Defaults to False. + generate_reports (bool, optional): Generate detailed conversion reports. Defaults to False. Returns: SyncResult: Result of the synchronization operation @@ -414,7 +531,9 @@ def sync_configurations(self, # Default to all available hosts if no targets specified if not to_hosts: - to_hosts = [host.value for host in self.host_registry.detect_available_hosts()] + to_hosts = [ + host.value for host in self.host_registry.detect_available_hosts() + ] try: # Resolve source data @@ -425,13 +544,15 @@ def sync_configurations(self, if not env_data: return SyncResult( success=False, - results=[ConfigurationResult( - success=False, - hostname="", - error_message=f"Environment '{from_env}' not found" - )], + results=[ + ConfigurationResult( + success=False, + hostname="", + error_message=f"Environment '{from_env}' not found", + ) + ], servers_synced=0, - hosts_updated=0 + hosts_updated=0, ) # Extract servers from environment @@ -457,26 +578,34 @@ def sync_configurations(self, except ValueError: return SyncResult( success=False, - results=[ConfigurationResult( - success=False, - hostname="", - error_message=f"Invalid source host '{from_host}'" - )], + results=[ + ConfigurationResult( + success=False, + hostname="", + error_message=f"Invalid source host '{from_host}'", + ) + ], servers_synced=0, - hosts_updated=0 + hosts_updated=0, ) # Apply server filtering if servers: # Filter by specific server names - filtered_servers = {name: config for name, config in source_servers.items() - if name in servers} + filtered_servers = { + name: config + for name, config in source_servers.items() + if name in servers + } source_servers = filtered_servers elif pattern: # Filter by regex pattern regex = re.compile(pattern) - filtered_servers = {name: config for name, config in source_servers.items() - if regex.match(name)} + filtered_servers = { + name: config + for name, config in source_servers.items() + if regex.match(name) + } source_servers = filtered_servers # Apply synchronization to target hosts @@ -496,12 +625,16 @@ def sync_configurations(self, if not no_backup and self.backup_manager: config_path = strategy.get_config_path() if config_path and config_path.exists(): - backup_result = self.backup_manager.create_backup(config_path, target_host) + backup_result = self.backup_manager.create_backup( + config_path, target_host + ) if backup_result.success: backup_path = backup_result.backup_path # Add servers to target configuration host_servers_added = 0 + host_conversion_reports = [] + for server_name, server_hosts in source_servers.items(): # Find appropriate server config for this target host server_config = None @@ -509,44 +642,74 @@ def sync_configurations(self, if from_env: # For environment source, look for host-specific config if target_host in server_hosts: - server_config = server_hosts[target_host]["server_config"] + server_config = server_hosts[target_host][ + "server_config" + ] elif "claude-desktop" in server_hosts: # Fallback to claude-desktop config for compatibility - server_config = server_hosts["claude-desktop"]["server_config"] + server_config = server_hosts["claude-desktop"][ + "server_config" + ] else: # For host source, use the server config directly if from_host in server_hosts: server_config = server_hosts[from_host]["server_config"] if server_config: + # Get existing config for comparison (if any) + old_config = current_config.servers.get(server_name) + + # Generate conversion report if requested + if generate_reports: + from .reporting import generate_conversion_report + + report = generate_conversion_report( + operation="update" if old_config else "create", + server_name=server_name, + target_host=host_type, + config=server_config, + old_config=old_config, + dry_run=False, + ) + host_conversion_reports.append(report) + current_config.add_server(server_name, server_config) host_servers_added += 1 # Write updated configuration - success = strategy.write_configuration(current_config, no_backup=no_backup) + success = strategy.write_configuration( + current_config, no_backup=no_backup + ) - results.append(ConfigurationResult( - success=success, - hostname=target_host, - backup_created=backup_path is not None, - backup_path=backup_path - )) + results.append( + ConfigurationResult( + success=success, + hostname=target_host, + backup_created=backup_path is not None, + backup_path=backup_path, + conversion_reports=host_conversion_reports + if generate_reports + else [], + ) + ) if success: servers_synced += host_servers_added except ValueError: - results.append(ConfigurationResult( - success=False, - hostname=target_host, - error_message=f"Invalid target host '{target_host}'" - )) + results.append( + ConfigurationResult( + success=False, + hostname=target_host, + error_message=f"Invalid target host '{target_host}'", + ) + ) except Exception as e: - results.append(ConfigurationResult( - success=False, - hostname=target_host, - error_message=str(e) - )) + results.append( + ConfigurationResult( + success=False, hostname=target_host, error_message=str(e) + ) + ) # Calculate summary statistics successful_results = [r for r in results if r.success] @@ -556,17 +719,19 @@ def sync_configurations(self, success=hosts_updated > 0, results=results, servers_synced=servers_synced, - hosts_updated=hosts_updated + hosts_updated=hosts_updated, ) except Exception as e: return SyncResult( success=False, - results=[ConfigurationResult( - success=False, - hostname="", - error_message=f"Synchronization failed: {str(e)}" - )], + results=[ + ConfigurationResult( + success=False, + hostname="", + error_message=f"Synchronization failed: {str(e)}", + ) + ], servers_synced=0, - hosts_updated=0 + hosts_updated=0, ) diff --git a/hatch/mcp_host_config/models.py b/hatch/mcp_host_config/models.py index b45079c..b7d146f 100644 --- a/hatch/mcp_host_config/models.py +++ b/hatch/mcp_host_config/models.py @@ -7,17 +7,21 @@ """ from pydantic import BaseModel, Field, field_validator, model_validator, ConfigDict -from typing import Dict, List, Optional, Union, Literal +from typing import Dict, List, Optional, Literal, TYPE_CHECKING from datetime import datetime from pathlib import Path from enum import Enum import logging +if TYPE_CHECKING: + from .reporting import ConversionReport + logger = logging.getLogger(__name__) class MCPHostType(str, Enum): """Enumeration of supported MCP host types.""" + CLAUDE_DESKTOP = "claude-desktop" CLAUDE_CODE = "claude-code" VSCODE = "vscode" @@ -29,43 +33,144 @@ class MCPHostType(str, Enum): class MCPServerConfig(BaseModel): - """Consolidated MCP server configuration supporting local and remote servers.""" + """Unified MCP server configuration containing ALL possible fields. + + This is the single source of truth for MCP server configuration. It contains + fields for ALL hosts. Adapters handle validation and serialization based on + each host's supported field set. + + Design Notes: + - extra="allow" for forward compatibility with unknown host fields + - Minimal validation (adapters do host-specific validation) + - 'name' field is Hatch metadata, never serialized to host configs + """ model_config = ConfigDict(extra="allow") - # Server identification + # ======================================================================== + # Hatch Metadata (never serialized to host config files) + # ======================================================================== name: Optional[str] = Field(None, description="Server name for identification") - # Transport type (PRIMARY DISCRIMINATOR) + # ======================================================================== + # Transport Fields (mutually exclusive at validation, but all present) + # ======================================================================== + + # Transport type discriminator (Claude/VSCode/Cursor only, NOT Gemini/Kiro/Codex) type: Optional[Literal["stdio", "sse", "http"]] = Field( - None, - description="Transport type (stdio for local, sse/http for remote)" + None, description="Transport type (stdio for local, sse/http for remote)" ) - # Local server configuration (Pattern A: Command-Based / stdio transport) - command: Optional[str] = Field(None, description="Executable path/name for local servers") - args: Optional[List[str]] = Field(None, description="Command arguments for local servers") - env: Optional[Dict[str, str]] = Field(None, description="Environment variables for all transports") + # stdio transport (local server) + command: Optional[str] = Field( + None, description="Executable path/name for local servers" + ) + args: Optional[List[str]] = Field( + None, description="Command arguments for local servers" + ) - # Remote server configuration (Pattern B: URL-Based / sse/http transports) - url: Optional[str] = Field(None, description="Server endpoint URL for remote servers") - headers: Optional[Dict[str, str]] = Field(None, description="HTTP headers for remote servers") - - @model_validator(mode='after') - def validate_server_type(self): - """Validate that either local or remote configuration is provided, not both.""" - command = self.command - url = self.url + # sse transport (remote server) + url: Optional[str] = Field(None, description="Server endpoint URL (SSE transport)") - if not command and not url: - raise ValueError("Either 'command' (local server) or 'url' (remote server) must be provided") + # http transport (Gemini-specific remote server) + httpUrl: Optional[str] = Field( + None, description="HTTP streaming endpoint URL (Gemini)" + ) - if command and url: - raise ValueError("Cannot specify both 'command' and 'url' - choose local or remote server") + # ======================================================================== + # Universal Fields (all hosts) + # ======================================================================== + env: Optional[Dict[str, str]] = Field(None, description="Environment variables") + headers: Optional[Dict[str, str]] = Field( + None, description="HTTP headers for remote servers" + ) - return self - - @field_validator('command') + # ======================================================================== + # Gemini-Specific Fields + # ======================================================================== + cwd: Optional[str] = Field(None, description="Working directory (Gemini/Codex)") + timeout: Optional[int] = Field(None, description="Request timeout in milliseconds") + trust: Optional[bool] = Field(None, description="Bypass tool call confirmations") + includeTools: Optional[List[str]] = Field( + None, description="Tools to include (allowlist)" + ) + excludeTools: Optional[List[str]] = Field( + None, description="Tools to exclude (blocklist)" + ) + + # OAuth configuration (Gemini) + oauth_enabled: Optional[bool] = Field( + None, description="Enable OAuth for this server" + ) + oauth_clientId: Optional[str] = Field(None, description="OAuth client identifier") + oauth_clientSecret: Optional[str] = Field(None, description="OAuth client secret") + oauth_authorizationUrl: Optional[str] = Field( + None, description="OAuth authorization endpoint" + ) + oauth_tokenUrl: Optional[str] = Field(None, description="OAuth token endpoint") + oauth_scopes: Optional[List[str]] = Field(None, description="Required OAuth scopes") + oauth_redirectUri: Optional[str] = Field(None, description="Custom redirect URI") + oauth_tokenParamName: Optional[str] = Field( + None, description="Query parameter name for tokens" + ) + oauth_audiences: Optional[List[str]] = Field(None, description="OAuth audiences") + authProviderType: Optional[str] = Field( + None, description="Authentication provider type" + ) + + # ======================================================================== + # VSCode/Cursor-Specific Fields + # ======================================================================== + envFile: Optional[str] = Field(None, description="Path to environment file") + inputs: Optional[List[Dict]] = Field( + None, description="Input variable definitions (VSCode only)" + ) + + # ======================================================================== + # Kiro-Specific Fields + # ======================================================================== + disabled: Optional[bool] = Field(None, description="Whether server is disabled") + autoApprove: Optional[List[str]] = Field( + None, description="Auto-approved tool names" + ) + disabledTools: Optional[List[str]] = Field(None, description="Disabled tool names") + + # ======================================================================== + # Codex-Specific Fields + # ======================================================================== + env_vars: Optional[List[str]] = Field( + None, description="Environment variables to whitelist/forward" + ) + startup_timeout_sec: Optional[int] = Field( + None, description="Server startup timeout in seconds" + ) + tool_timeout_sec: Optional[int] = Field( + None, description="Tool execution timeout in seconds" + ) + enabled: Optional[bool] = Field( + None, description="Enable/disable server without deleting config" + ) + enabled_tools: Optional[List[str]] = Field( + None, description="Allow-list of tools to expose" + ) + disabled_tools: Optional[List[str]] = Field( + None, description="Deny-list of tools to hide" + ) + bearer_token_env_var: Optional[str] = Field( + None, description="Env var containing bearer token" + ) + http_headers: Optional[Dict[str, str]] = Field( + None, description="HTTP headers (Codex naming)" + ) + env_http_headers: Optional[Dict[str, str]] = Field( + None, description="Header names to env var names" + ) + + # ======================================================================== + # Minimal Validators (host-specific validation is in adapters) + # ======================================================================== + + @field_validator("command") @classmethod def validate_command_not_empty(cls, v): """Validate command is not empty when provided.""" @@ -73,74 +178,118 @@ def validate_command_not_empty(cls, v): raise ValueError("Command cannot be empty") return v.strip() if v else v - @field_validator('url') + @field_validator("url", "httpUrl") @classmethod def validate_url_format(cls, v): """Validate URL format when provided.""" if v is not None: - if not v.startswith(('http://', 'https://')): + if not v.startswith(("http://", "https://")): raise ValueError("URL must start with http:// or https://") return v - @model_validator(mode='after') - def validate_field_combinations(self): - """Validate field combinations for local vs remote servers.""" - # Validate args are only provided with command - if self.args is not None and self.command is None: - raise ValueError("'args' can only be specified with 'command' for local servers") - - # Validate headers are only provided with URL - if self.headers is not None and self.url is None: - raise ValueError("'headers' can only be specified with 'url' for remote servers") + @model_validator(mode="after") + def validate_has_transport(self): + """Validate that at least one transport is configured. + Note: Mutual exclusion validation is done by adapters, not here. + This allows the unified model to be flexible while adapters enforce + host-specific rules. + """ + if self.command is None and self.url is None and self.httpUrl is None: + raise ValueError( + "At least one transport must be specified: " + "'command' (stdio), 'url' (sse), or 'httpUrl' (http)" + ) return self - @model_validator(mode='after') - def validate_type_field(self): - """Validate type field consistency with command/url fields.""" - # Only validate if type field is explicitly set - if self.type is not None: - if self.type == "stdio": - if not self.command: - raise ValueError("'type=stdio' requires 'command' field") - if self.url: - raise ValueError("'type=stdio' cannot be used with 'url' field") - elif self.type in ("sse", "http"): - if not self.url: - raise ValueError(f"'type={self.type}' requires 'url' field") - if self.command: - raise ValueError(f"'type={self.type}' cannot be used with 'command' field") - - return self + # ======================================================================== + # Transport Detection Properties + # ======================================================================== @property def is_local_server(self) -> bool: - """Check if this is a local server configuration.""" - # Prioritize type field if present + """Check if this is a local server configuration (stdio transport).""" + return self.is_stdio() + + @property + def is_remote_server(self) -> bool: + """Check if this is a remote server configuration (sse/http transport).""" + return self.is_sse() or self.is_http() + + def is_stdio(self) -> bool: + """Check if this server uses stdio transport (command-based local server). + + Returns: + True if the server is configured for stdio transport. + + Priority: + 1. Explicit type="stdio" field takes precedence + 2. Otherwise, presence of 'command' field indicates stdio + """ if self.type is not None: return self.type == "stdio" - # Fall back to command detection for backward compatibility return self.command is not None - @property - def is_remote_server(self) -> bool: - """Check if this is a remote server configuration.""" - # Prioritize type field if present + def is_sse(self) -> bool: + """Check if this server uses SSE transport (URL-based remote server). + + Returns: + True if the server is configured for SSE transport. + + Priority: + 1. Explicit type="sse" field takes precedence + 2. Otherwise, presence of 'url' field indicates SSE + """ if self.type is not None: - return self.type in ("sse", "http") - # Fall back to url detection for backward compatibility + return self.type == "sse" return self.url is not None - + def is_http(self) -> bool: + """Check if this server uses HTTP streaming transport (Gemini-specific). + + Returns: + True if the server is configured for HTTP streaming transport. + + Priority: + 1. Explicit type="http" field takes precedence + 2. Otherwise, presence of 'httpUrl' field indicates HTTP streaming + """ + if self.type is not None: + return self.type == "http" + return self.httpUrl is not None + + def get_transport_type(self) -> Optional[str]: + """Get the transport type for this server configuration. + + Returns: + "stdio" for command-based local servers + "sse" for URL-based remote servers (SSE transport) + "http" for httpUrl-based remote servers (Gemini HTTP streaming) + None if transport cannot be determined + """ + # Explicit type takes precedence + if self.type is not None: + return self.type + + # Infer from fields + if self.command is not None: + return "stdio" + if self.url is not None: + return "sse" + if self.httpUrl is not None: + return "http" + + return None class HostConfigurationMetadata(BaseModel): """Metadata for host configuration tracking.""" + config_path: str = Field(..., description="Path to host configuration file") configured_at: datetime = Field(..., description="Initial configuration timestamp") last_synced: datetime = Field(..., description="Last synchronization timestamp") - - @field_validator('config_path') + + @field_validator("config_path") @classmethod def validate_config_path_not_empty(cls, v): """Validate config path is not empty.""" @@ -151,12 +300,15 @@ def validate_config_path_not_empty(cls, v): class PackageHostConfiguration(BaseModel): """Host configuration for a single package (corrected structure).""" + config_path: str = Field(..., description="Path to host configuration file") configured_at: datetime = Field(..., description="Initial configuration timestamp") last_synced: datetime = Field(..., description="Last synchronization timestamp") - server_config: MCPServerConfig = Field(..., description="Server configuration for this host") - - @field_validator('config_path') + server_config: MCPServerConfig = Field( + ..., description="Server configuration for this host" + ) + + @field_validator("config_path") @classmethod def validate_config_path_format(cls, v): """Validate config path format.""" @@ -167,6 +319,7 @@ def validate_config_path_format(cls, v): class EnvironmentPackageEntry(BaseModel): """Package entry within environment with corrected MCP structure.""" + name: str = Field(..., description="Package name") version: str = Field(..., description="Package version") type: str = Field(..., description="Package type (hatch, mcp_standalone, etc.)") @@ -174,69 +327,82 @@ class EnvironmentPackageEntry(BaseModel): installed_at: datetime = Field(..., description="Installation timestamp") configured_hosts: Dict[str, PackageHostConfiguration] = Field( default_factory=dict, - description="Host configurations for this package's MCP server" + description="Host configurations for this package's MCP server", ) - - @field_validator('name') + + @field_validator("name") @classmethod def validate_package_name(cls, v): """Validate package name format.""" if not v.strip(): raise ValueError("Package name cannot be empty") # Allow standard package naming patterns - if not v.replace('-', '').replace('_', '').replace('.', '').isalnum(): + if not v.replace("-", "").replace("_", "").replace(".", "").isalnum(): raise ValueError(f"Invalid package name format: {v}") return v.strip() - @field_validator('configured_hosts') + @field_validator("configured_hosts") @classmethod def validate_host_names(cls, v): """Validate host names are supported.""" supported_hosts = { - 'claude-desktop', 'claude-code', 'vscode', - 'cursor', 'lmstudio', 'gemini', 'kiro' + "claude-desktop", + "claude-code", + "vscode", + "cursor", + "lmstudio", + "gemini", + "kiro", } for host_name in v.keys(): if host_name not in supported_hosts: - raise ValueError(f"Unsupported host: {host_name}. Supported: {supported_hosts}") + raise ValueError( + f"Unsupported host: {host_name}. Supported: {supported_hosts}" + ) return v class EnvironmentData(BaseModel): """Complete environment data structure with corrected MCP integration.""" + name: str = Field(..., description="Environment name") description: str = Field(..., description="Environment description") created_at: datetime = Field(..., description="Environment creation timestamp") packages: List[EnvironmentPackageEntry] = Field( - default_factory=list, - description="Packages installed in this environment" + default_factory=list, description="Packages installed in this environment" + ) + python_environment: bool = Field( + True, description="Whether this is a Python environment" ) - python_environment: bool = Field(True, description="Whether this is a Python environment") - python_env: Dict = Field(default_factory=dict, description="Python environment data") - - @field_validator('name') + python_env: Dict = Field( + default_factory=dict, description="Python environment data" + ) + + @field_validator("name") @classmethod def validate_environment_name(cls, v): """Validate environment name format.""" if not v.strip(): raise ValueError("Environment name cannot be empty") return v.strip() - + def get_mcp_packages(self) -> List[EnvironmentPackageEntry]: """Get packages that have MCP server configurations.""" return [pkg for pkg in self.packages if pkg.configured_hosts] - + def get_standalone_mcp_package(self) -> Optional[EnvironmentPackageEntry]: """Get the standalone MCP servers package if it exists.""" for pkg in self.packages: if pkg.name == "__standalone_mcp_servers__": return pkg return None - - def add_standalone_mcp_server(self, server_name: str, host_config: PackageHostConfiguration): + + def add_standalone_mcp_server( + self, server_name: str, host_config: PackageHostConfiguration + ): """Add a standalone MCP server configuration.""" standalone_pkg = self.get_standalone_mcp_package() - + if standalone_pkg is None: # Create standalone package entry standalone_pkg = EnvironmentPackageEntry( @@ -245,10 +411,10 @@ def add_standalone_mcp_server(self, server_name: str, host_config: PackageHostCo type="mcp_standalone", source="user_configured", installed_at=datetime.now(), - configured_hosts={} + configured_hosts={}, ) self.packages.append(standalone_pkg) - + # Add host configuration (single server per package constraint) for host_name, config in host_config.items(): standalone_pkg.configured_hosts[host_name] = config @@ -256,12 +422,12 @@ def add_standalone_mcp_server(self, server_name: str, host_config: PackageHostCo class HostConfiguration(BaseModel): """Host configuration file structure using consolidated MCPServerConfig.""" + servers: Dict[str, MCPServerConfig] = Field( - default_factory=dict, - description="Configured MCP servers" + default_factory=dict, description="Configured MCP servers" ) - - @field_validator('servers') + + @field_validator("servers") @classmethod def validate_servers_not_empty_when_present(cls, v): """Validate servers dict structure.""" @@ -269,34 +435,40 @@ def validate_servers_not_empty_when_present(cls, v): if not isinstance(config, (dict, MCPServerConfig)): raise ValueError(f"Invalid server config for {server_name}") return v - + def add_server(self, name: str, config: MCPServerConfig): """Add server configuration.""" self.servers[name] = config - + def remove_server(self, name: str) -> bool: """Remove server configuration.""" if name in self.servers: del self.servers[name] return True return False - + class Config: """Pydantic configuration.""" + arbitrary_types_allowed = True extra = "allow" # Allow additional host-specific fields class ConfigurationResult(BaseModel): """Result of a configuration operation.""" + success: bool = Field(..., description="Whether operation succeeded") hostname: str = Field(..., description="Target hostname") server_name: Optional[str] = Field(None, description="Server name if applicable") backup_created: bool = Field(False, description="Whether backup was created") backup_path: Optional[Path] = Field(None, description="Path to backup file") error_message: Optional[str] = Field(None, description="Error message if failed") - - @model_validator(mode='after') + conversion_reports: List["ConversionReport"] = Field( + default_factory=list, + description="Detailed conversion reports for each server (optional)", + ) + + @model_validator(mode="after") def validate_result_consistency(self): """Validate result consistency.""" if not self.success and not self.error_message: @@ -307,16 +479,19 @@ def validate_result_consistency(self): class SyncResult(BaseModel): """Result of environment synchronization operation.""" + success: bool = Field(..., description="Whether overall sync succeeded") - results: List[ConfigurationResult] = Field(..., description="Individual host results") + results: List[ConfigurationResult] = Field( + ..., description="Individual host results" + ) servers_synced: int = Field(..., description="Total servers synchronized") hosts_updated: int = Field(..., description="Number of hosts updated") - + @property def failed_hosts(self) -> List[str]: """Get list of hosts that failed synchronization.""" return [r.hostname for r in self.results if not r.success] - + @property def success_rate(self) -> float: """Calculate success rate percentage.""" @@ -326,401 +501,11 @@ def success_rate(self) -> float: return (successful / len(self.results)) * 100.0 -# ============================================================================ -# MCP Host-Specific Configuration Models -# ============================================================================ - - -class MCPServerConfigBase(BaseModel): - """Base class for MCP server configurations with universal fields. - - This model contains fields supported by ALL MCP hosts and provides - transport validation logic. Host-specific models inherit from this base. - """ - - model_config = ConfigDict(extra="forbid") - - # Hatch-specific field - name: Optional[str] = Field(None, description="Server name for identification") - - # Transport type (PRIMARY DISCRIMINATOR) - type: Optional[Literal["stdio", "sse", "http"]] = Field( - None, - description="Transport type (stdio for local, sse/http for remote)" - ) - - # stdio transport fields - command: Optional[str] = Field(None, description="Server executable command") - args: Optional[List[str]] = Field(None, description="Command arguments") - - # All transports - env: Optional[Dict[str, str]] = Field(None, description="Environment variables") - - # Remote transport fields (sse/http) - url: Optional[str] = Field(None, description="Remote server endpoint") - headers: Optional[Dict[str, str]] = Field(None, description="HTTP headers") - - @model_validator(mode='after') - def validate_transport(self) -> 'MCPServerConfigBase': - """Validate transport configuration using type field. - - Note: Gemini subclass overrides this with dual-transport support. - """ - # Skip validation for Gemini which has its own dual-transport validator - if self.__class__.__name__ == 'MCPServerConfigGemini': - return self - - # Check mutual exclusion - command and url cannot both be set - if self.command is not None and self.url is not None: - raise ValueError( - "Cannot specify both 'command' and 'url' - use 'type' field to specify transport" - ) - - # Validate based on type - if self.type == "stdio": - if not self.command: - raise ValueError("'command' is required for stdio transport") - elif self.type in ("sse", "http"): - if not self.url: - raise ValueError("'url' is required for sse/http transports") - elif self.type is None: - # Infer type from fields if not specified - if self.command: - self.type = "stdio" - elif self.url: - self.type = "sse" # default to sse for remote - else: - raise ValueError("Either 'command' or 'url' must be provided") - - return self - - -class MCPServerConfigGemini(MCPServerConfigBase): - """Gemini CLI-specific MCP server configuration. - - Extends base model with Gemini-specific fields including working directory, - timeout, trust mode, tool filtering, and OAuth configuration. - """ - - # Gemini-specific fields - cwd: Optional[str] = Field(None, description="Working directory for stdio transport") - timeout: Optional[int] = Field(None, description="Request timeout in milliseconds") - trust: Optional[bool] = Field(None, description="Bypass tool call confirmations") - httpUrl: Optional[str] = Field(None, description="HTTP streaming endpoint URL") - includeTools: Optional[List[str]] = Field(None, description="Tools to include (allowlist)") - excludeTools: Optional[List[str]] = Field(None, description="Tools to exclude (blocklist)") - - # OAuth configuration (simplified - nested object would be better but keeping flat for now) - oauth_enabled: Optional[bool] = Field(None, description="Enable OAuth for this server") - oauth_clientId: Optional[str] = Field(None, description="OAuth client identifier") - oauth_clientSecret: Optional[str] = Field(None, description="OAuth client secret") - oauth_authorizationUrl: Optional[str] = Field(None, description="OAuth authorization endpoint") - oauth_tokenUrl: Optional[str] = Field(None, description="OAuth token endpoint") - oauth_scopes: Optional[List[str]] = Field(None, description="Required OAuth scopes") - oauth_redirectUri: Optional[str] = Field(None, description="Custom redirect URI") - oauth_tokenParamName: Optional[str] = Field(None, description="Query parameter name for tokens") - oauth_audiences: Optional[List[str]] = Field(None, description="OAuth audiences") - authProviderType: Optional[str] = Field(None, description="Authentication provider type") - - @model_validator(mode='after') - def validate_gemini_dual_transport(self): - """Override transport validation to support Gemini's dual-transport capability. - - Gemini supports both: - - SSE transport with 'url' field - - HTTP transport with 'httpUrl' field - - Validates that: - 1. Either url or httpUrl is provided (not both) - 2. Type field matches the transport being used - """ - # Check if both url and httpUrl are provided - if self.url is not None and self.httpUrl is not None: - raise ValueError("Cannot specify both 'url' and 'httpUrl' - choose one transport") - - # Validate based on type - if self.type == "stdio": - if not self.command: - raise ValueError("'command' is required for stdio transport") - elif self.type == "sse": - if not self.url: - raise ValueError("'url' is required for sse transport") - elif self.type == "http": - if not self.httpUrl: - raise ValueError("'httpUrl' is required for http transport") - elif self.type is None: - # Infer type from fields if not specified - if self.command: - self.type = "stdio" - elif self.url: - self.type = "sse" # default to sse for url - elif self.httpUrl: - self.type = "http" # http for httpUrl - else: - raise ValueError("Either 'command', 'url', or 'httpUrl' must be provided") - - return self - - @classmethod - def from_omni(cls, omni: 'MCPServerConfigOmni') -> 'MCPServerConfigGemini': - """Convert Omni model to Gemini-specific model using Pydantic APIs.""" - # Get supported fields dynamically from model definition - supported_fields = set(cls.model_fields.keys()) - - # Use Pydantic's model_dump with include and exclude_unset - gemini_data = omni.model_dump(include=supported_fields, exclude_unset=True) - - # Use Pydantic's model_validate for type-safe creation - return cls.model_validate(gemini_data) - - -class MCPServerConfigVSCode(MCPServerConfigBase): - """VS Code-specific MCP server configuration. - - Extends base model with VS Code-specific fields including environment file - path and input variable definitions. - """ - - # VS Code-specific fields - envFile: Optional[str] = Field(None, description="Path to environment file") - inputs: Optional[List[Dict]] = Field(None, description="Input variable definitions") - - @classmethod - def from_omni(cls, omni: 'MCPServerConfigOmni') -> 'MCPServerConfigVSCode': - """Convert Omni model to VS Code-specific model.""" - # Get supported fields dynamically - supported_fields = set(cls.model_fields.keys()) - - # Single-call field filtering - vscode_data = omni.model_dump(include=supported_fields, exclude_unset=True) - - return cls.model_validate(vscode_data) - - -class MCPServerConfigCursor(MCPServerConfigBase): - """Cursor/LM Studio-specific MCP server configuration. - - Extends base model with Cursor-specific fields including environment file path. - Cursor handles config interpolation (${env:NAME}, ${userHome}, etc.) at runtime. - """ - - # Cursor-specific fields - envFile: Optional[str] = Field(None, description="Path to environment file") - - @classmethod - def from_omni(cls, omni: 'MCPServerConfigOmni') -> 'MCPServerConfigCursor': - """Convert Omni model to Cursor-specific model.""" - # Get supported fields dynamically - supported_fields = set(cls.model_fields.keys()) - - # Single-call field filtering - cursor_data = omni.model_dump(include=supported_fields, exclude_unset=True) - - return cls.model_validate(cursor_data) - - -class MCPServerConfigClaude(MCPServerConfigBase): - """Claude Desktop/Code-specific MCP server configuration. - - Uses only universal fields from base model. Supports all transport types - (stdio, sse, http). Claude handles environment variable expansion at runtime. - """ - - # No host-specific fields - uses universal fields only - - @classmethod - def from_omni(cls, omni: 'MCPServerConfigOmni') -> 'MCPServerConfigClaude': - """Convert Omni model to Claude-specific model.""" - # Get supported fields dynamically - supported_fields = set(cls.model_fields.keys()) - - # Single-call field filtering - claude_data = omni.model_dump(include=supported_fields, exclude_unset=True) - - return cls.model_validate(claude_data) - - -class MCPServerConfigKiro(MCPServerConfigBase): - """Kiro IDE-specific MCP server configuration. - - Extends base model with Kiro-specific fields for server management - and tool control. - """ - - # Kiro-specific fields - disabled: Optional[bool] = Field(None, description="Whether server is disabled") - autoApprove: Optional[List[str]] = Field(None, description="Auto-approved tool names") - disabledTools: Optional[List[str]] = Field(None, description="Disabled tool names") - - @classmethod - def from_omni(cls, omni: 'MCPServerConfigOmni') -> 'MCPServerConfigKiro': - """Convert Omni model to Kiro-specific model.""" - # Get supported fields dynamically - supported_fields = set(cls.model_fields.keys()) - - # Single-call field filtering - kiro_data = omni.model_dump(include=supported_fields, exclude_unset=True) - - return cls.model_validate(kiro_data) - - -class MCPServerConfigCodex(MCPServerConfigBase): - """Codex-specific MCP server configuration. - - Extends base model with Codex-specific fields including timeouts, - tool filtering, environment variable forwarding, and HTTP authentication. - """ - - model_config = ConfigDict(extra="forbid") - - # Codex-specific STDIO fields - env_vars: Optional[List[str]] = Field( - None, - description="Environment variables to whitelist/forward" - ) - cwd: Optional[str] = Field( - None, - description="Working directory to launch server from" - ) - - # Timeout configuration - startup_timeout_sec: Optional[int] = Field( - None, - description="Server startup timeout in seconds (default: 10)" - ) - tool_timeout_sec: Optional[int] = Field( - None, - description="Tool execution timeout in seconds (default: 60)" - ) - - # Server control - enabled: Optional[bool] = Field( - None, - description="Enable/disable server without deleting config" - ) - enabled_tools: Optional[List[str]] = Field( - None, - description="Allow-list of tools to expose from server" - ) - disabled_tools: Optional[List[str]] = Field( - None, - description="Deny-list of tools to hide (applied after enabled_tools)" - ) - - # HTTP authentication fields - bearer_token_env_var: Optional[str] = Field( - None, - description="Name of env var containing bearer token for Authorization header" - ) - http_headers: Optional[Dict[str, str]] = Field( - None, - description="Map of header names to static values" - ) - env_http_headers: Optional[Dict[str, str]] = Field( - None, - description="Map of header names to env var names (values pulled from env)" - ) - - @classmethod - def from_omni(cls, omni: 'MCPServerConfigOmni') -> 'MCPServerConfigCodex': - """Convert Omni model to Codex-specific model. - - Maps universal 'headers' field to Codex-specific 'http_headers' field. - """ - supported_fields = set(cls.model_fields.keys()) - codex_data = omni.model_dump(include=supported_fields, exclude_unset=True) - - # Map shared CLI tool filtering flags (Gemini naming) to Codex naming. - # This lets `--include-tools/--exclude-tools` work for both Gemini and Codex. - if getattr(omni, 'includeTools', None) is not None and codex_data.get('enabled_tools') is None: - codex_data['enabled_tools'] = omni.includeTools - if getattr(omni, 'excludeTools', None) is not None and codex_data.get('disabled_tools') is None: - codex_data['disabled_tools'] = omni.excludeTools - - # Map universal 'headers' to Codex 'http_headers' - if hasattr(omni, 'headers') and omni.headers is not None: - codex_data['http_headers'] = omni.headers - - return cls.model_validate(codex_data) - - -class MCPServerConfigOmni(BaseModel): - """Omni configuration supporting all host-specific fields. - - This is the primary API interface for MCP server configuration. It contains - all possible fields from all hosts. Use host-specific models' from_omni() - methods to convert to host-specific configurations. - """ - - model_config = ConfigDict(extra="forbid") - - # Hatch-specific - name: Optional[str] = None - - # Universal fields (all hosts) - type: Optional[Literal["stdio", "sse", "http"]] = None - command: Optional[str] = None - args: Optional[List[str]] = None - env: Optional[Dict[str, str]] = None - url: Optional[str] = None - headers: Optional[Dict[str, str]] = None - - # Gemini CLI specific - cwd: Optional[str] = None - timeout: Optional[int] = None - trust: Optional[bool] = None - httpUrl: Optional[str] = None - includeTools: Optional[List[str]] = None - excludeTools: Optional[List[str]] = None - oauth_enabled: Optional[bool] = None - oauth_clientId: Optional[str] = None - oauth_clientSecret: Optional[str] = None - oauth_authorizationUrl: Optional[str] = None - oauth_tokenUrl: Optional[str] = None - oauth_scopes: Optional[List[str]] = None - oauth_redirectUri: Optional[str] = None - oauth_tokenParamName: Optional[str] = None - oauth_audiences: Optional[List[str]] = None - authProviderType: Optional[str] = None - - # VS Code specific - envFile: Optional[str] = None - inputs: Optional[List[Dict]] = None - - # Kiro specific - disabled: Optional[bool] = None - autoApprove: Optional[List[str]] = None - disabledTools: Optional[List[str]] = None - - # Codex specific - env_vars: Optional[List[str]] = None - startup_timeout_sec: Optional[int] = None - tool_timeout_sec: Optional[int] = None - enabled: Optional[bool] = None - enabled_tools: Optional[List[str]] = None - disabled_tools: Optional[List[str]] = None - bearer_token_env_var: Optional[str] = None - env_http_headers: Optional[Dict[str, str]] = None - # Note: http_headers maps to universal 'headers' field, not a separate Codex field - - @field_validator('url') - @classmethod - def validate_url_format(cls, v): - """Validate URL format when provided.""" - if v is not None: - if not v.startswith(('http://', 'https://')): - raise ValueError("URL must start with http:// or https://") - return v - +# Rebuild models to resolve forward references +if TYPE_CHECKING: + pass +else: + # Import at runtime to avoid circular dependency + from .reporting import ConversionReport -# HOST_MODEL_REGISTRY: Dictionary dispatch for host-specific models -HOST_MODEL_REGISTRY: Dict[MCPHostType, type[MCPServerConfigBase]] = { - MCPHostType.GEMINI: MCPServerConfigGemini, - MCPHostType.CLAUDE_DESKTOP: MCPServerConfigClaude, - MCPHostType.CLAUDE_CODE: MCPServerConfigClaude, # Same as CLAUDE_DESKTOP - MCPHostType.VSCODE: MCPServerConfigVSCode, - MCPHostType.CURSOR: MCPServerConfigCursor, - MCPHostType.LMSTUDIO: MCPServerConfigCursor, # Same as CURSOR - MCPHostType.KIRO: MCPServerConfigKiro, - MCPHostType.CODEX: MCPServerConfigCodex, -} + ConfigurationResult.model_rebuild() diff --git a/hatch/mcp_host_config/reporting.py b/hatch/mcp_host_config/reporting.py index 2710a05..8791f93 100644 --- a/hatch/mcp_host_config/reporting.py +++ b/hatch/mcp_host_config/reporting.py @@ -9,24 +9,25 @@ from typing import Literal, Optional, Any, List from pydantic import BaseModel, ConfigDict -from .models import MCPServerConfigOmni, MCPHostType, HOST_MODEL_REGISTRY +from .models import MCPServerConfig, MCPHostType +from .adapters import get_adapter class FieldOperation(BaseModel): """Single field operation in a conversion. - + Represents a single field-level change during MCP configuration conversion, including the operation type (UPDATED, UNSUPPORTED, UNCHANGED) and values. """ - + field_name: str operation: Literal["UPDATED", "UNSUPPORTED", "UNCHANGED"] old_value: Optional[Any] = None new_value: Optional[Any] = None - + def __str__(self) -> str: """Return formatted string representation for console output. - + Uses ASCII arrow (-->) for terminal compatibility instead of Unicode. """ if self.operation == "UPDATED": @@ -40,13 +41,13 @@ def __str__(self) -> str: class ConversionReport(BaseModel): """Complete conversion report for a configuration operation. - + Contains metadata about the operation (create, update, delete, migrate) and a list of field-level operations that occurred during conversion. """ - + model_config = ConfigDict(validate_assignment=False) - + operation: Literal["create", "update", "delete", "migrate"] server_name: str source_host: Optional[MCPHostType] = None @@ -57,41 +58,70 @@ class ConversionReport(BaseModel): dry_run: bool = False +def _get_adapter_host_name(host_type: MCPHostType) -> str: + """Map MCPHostType to adapter host name. + + Claude has two variants (desktop/code) sharing the same adapter, + so we need explicit mapping. + """ + mapping = { + MCPHostType.CLAUDE_DESKTOP: "claude-desktop", + MCPHostType.CLAUDE_CODE: "claude-code", + MCPHostType.VSCODE: "vscode", + MCPHostType.CURSOR: "cursor", + MCPHostType.LMSTUDIO: "lmstudio", + MCPHostType.GEMINI: "gemini", + MCPHostType.KIRO: "kiro", + MCPHostType.CODEX: "codex", + } + return mapping.get(host_type, host_type.value) + + def generate_conversion_report( operation: Literal["create", "update", "delete", "migrate"], server_name: str, target_host: MCPHostType, - omni: MCPServerConfigOmni, + config: MCPServerConfig, source_host: Optional[MCPHostType] = None, - old_config: Optional[MCPServerConfigOmni] = None, - dry_run: bool = False + old_config: Optional[MCPServerConfig] = None, + dry_run: bool = False, ) -> ConversionReport: """Generate conversion report for a configuration operation. - - Analyzes the conversion from Omni model to host-specific configuration, + + Analyzes the configuration against the target host's adapter, identifying which fields were updated, which are unsupported, and which remained unchanged. - + + Fields in the adapter's excluded set (e.g., 'name' from EXCLUDED_ALWAYS) + are internal metadata and are completely omitted from field operations. + They will not appear as UPDATED, UNCHANGED, or UNSUPPORTED. + Args: operation: Type of operation being performed server_name: Name of the server being configured target_host: Target host for the configuration (MCPHostType enum) - omni: New/updated configuration (Omni model) + config: New/updated configuration (unified MCPServerConfig) source_host: Source host (for migrate operation, MCPHostType enum) old_config: Existing configuration (for update operation) dry_run: Whether this is a dry-run preview - + Returns: ConversionReport with field-level operations """ - # Derive supported fields dynamically from model class - model_class = HOST_MODEL_REGISTRY[target_host] - supported_fields = set(model_class.model_fields.keys()) - + # Get supported and excluded fields from adapter + adapter_host_name = _get_adapter_host_name(target_host) + adapter = get_adapter(adapter_host_name) + supported_fields = adapter.get_supported_fields() + excluded_fields = adapter.get_excluded_fields() + field_operations = [] - set_fields = omni.model_dump(exclude_unset=True) - + set_fields = config.model_dump(exclude_unset=True) + for field_name, new_value in set_fields.items(): + # Skip metadata fields (e.g., 'name') - they should never appear in reports + if field_name in excluded_fields: + continue + if field_name in supported_fields: # Field is supported by target host if old_config: @@ -101,81 +131,108 @@ def generate_conversion_report( old_value = old_fields[field_name] if old_value != new_value: # Field was modified - field_operations.append(FieldOperation( - field_name=field_name, - operation="UPDATED", - old_value=old_value, - new_value=new_value - )) + field_operations.append( + FieldOperation( + field_name=field_name, + operation="UPDATED", + old_value=old_value, + new_value=new_value, + ) + ) else: # Field unchanged - field_operations.append(FieldOperation( - field_name=field_name, - operation="UNCHANGED", - new_value=new_value - )) + field_operations.append( + FieldOperation( + field_name=field_name, + operation="UNCHANGED", + new_value=new_value, + ) + ) else: # Field was added - field_operations.append(FieldOperation( + field_operations.append( + FieldOperation( + field_name=field_name, + operation="UPDATED", + old_value=None, + new_value=new_value, + ) + ) + else: + # Create operation - all fields are new + field_operations.append( + FieldOperation( field_name=field_name, operation="UPDATED", old_value=None, - new_value=new_value - )) - else: - # Create operation - all fields are new - field_operations.append(FieldOperation( - field_name=field_name, - operation="UPDATED", - old_value=None, - new_value=new_value - )) + new_value=new_value, + ) + ) else: # Field is not supported by target host - field_operations.append(FieldOperation( - field_name=field_name, - operation="UNSUPPORTED", - new_value=new_value - )) - + field_operations.append( + FieldOperation( + field_name=field_name, operation="UNSUPPORTED", new_value=new_value + ) + ) + return ConversionReport( operation=operation, server_name=server_name, source_host=source_host, target_host=target_host, field_operations=field_operations, - dry_run=dry_run + dry_run=dry_run, ) def display_report(report: ConversionReport) -> None: """Display conversion report to console. - + + .. deprecated:: + Use ``ResultReporter.add_from_conversion_report()`` instead. + This function will be removed in a future version. + Prints a formatted report showing the operation performed and all field-level changes. Uses FieldOperation.__str__() for consistent formatting. - + Args: report: ConversionReport to display """ + import warnings + + warnings.warn( + "display_report() is deprecated. Use ResultReporter.add_from_conversion_report() instead.", + DeprecationWarning, + stacklevel=2, + ) + # Header if report.dry_run: print(f"[DRY RUN] Preview of changes for server '{report.server_name}':") else: if report.operation == "create": - print(f"Server '{report.server_name}' created for host '{report.target_host.value}':") + print( + f"Server '{report.server_name}' created for host '{report.target_host.value}':" + ) elif report.operation == "update": - print(f"Server '{report.server_name}' updated for host '{report.target_host.value}':") + print( + f"Server '{report.server_name}' updated for host '{report.target_host.value}':" + ) elif report.operation == "migrate": - print(f"Server '{report.server_name}' migrated from '{report.source_host.value}' to '{report.target_host.value}':") + print( + f"Server '{report.server_name}' migrated from '{report.source_host.value}' to '{report.target_host.value}':" + ) elif report.operation == "delete": - print(f"Server '{report.server_name}' deleted from host '{report.target_host.value}':") - + print( + f"Server '{report.server_name}' deleted from host '{report.target_host.value}':" + ) + # Field operations for field_op in report.field_operations: print(f" {field_op}") - + # Footer if report.dry_run: print("\nNo changes were made.") - diff --git a/hatch/mcp_host_config/strategies.py b/hatch/mcp_host_config/strategies.py index c5345af..5f1523d 100644 --- a/hatch/mcp_host_config/strategies.py +++ b/hatch/mcp_host_config/strategies.py @@ -17,24 +17,33 @@ from .host_management import MCPHostStrategy, register_host_strategy from .models import MCPHostType, MCPServerConfig, HostConfiguration from .backup import MCPHostConfigBackupManager, AtomicFileOperations +from .adapters import get_adapter logger = logging.getLogger(__name__) class ClaudeHostStrategy(MCPHostStrategy): """Base strategy for Claude family hosts with shared patterns.""" - + def __init__(self): self.company_origin = "Anthropic" self.config_format = "claude_format" - + + def get_adapter_host_name(self) -> str: + """Return the adapter host name for this strategy. + + Subclasses should override to return their specific adapter host name. + Default is 'claude-desktop' for backward compatibility. + """ + return "claude-desktop" + def get_config_key(self) -> str: """Claude family uses 'mcpServers' key.""" return "mcpServers" - + def validate_server_config(self, server_config: MCPServerConfig) -> bool: """Claude family validation - accepts any valid command or URL. - + Claude Desktop accepts both absolute and relative paths for commands. Commands are resolved at runtime using the system PATH, similar to how shell commands work. This validation only checks that either a @@ -48,27 +57,29 @@ def validate_server_config(self, server_config: MCPServerConfig) -> bool: return True # Reject if neither command nor URL is provided return False - - def _preserve_claude_settings(self, existing_config: Dict, new_servers: Dict) -> Dict: + + def _preserve_claude_settings( + self, existing_config: Dict, new_servers: Dict + ) -> Dict: """Preserve Claude-specific settings when updating configuration.""" # Preserve non-MCP settings like theme, auto_update, etc. preserved_config = existing_config.copy() preserved_config[self.get_config_key()] = new_servers return preserved_config - + def read_configuration(self) -> HostConfiguration: """Read Claude configuration file.""" config_path = self.get_config_path() if not config_path or not config_path.exists(): return HostConfiguration() - + try: - with open(config_path, 'r') as f: + with open(config_path, "r") as f: config_data = json.load(f) - + # Extract MCP servers from Claude configuration mcp_servers = config_data.get(self.get_config_key(), {}) - + # Convert to MCPServerConfig objects servers = {} for name, server_data in mcp_servers.items(): @@ -77,48 +88,53 @@ def read_configuration(self) -> HostConfiguration: except Exception as e: logger.warning(f"Invalid server config for {name}: {e}") continue - + return HostConfiguration(servers=servers) - + except Exception as e: logger.error(f"Failed to read Claude configuration: {e}") return HostConfiguration() - - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write Claude configuration file.""" + + def write_configuration( + self, config: HostConfiguration, no_backup: bool = False + ) -> bool: + """Write Claude configuration file using adapter-based serialization.""" config_path = self.get_config_path() if not config_path: return False - + try: # Ensure parent directory exists config_path.parent.mkdir(parents=True, exist_ok=True) - + # Read existing configuration to preserve non-MCP settings existing_config = {} if config_path.exists(): try: - with open(config_path, 'r') as f: + with open(config_path, "r") as f: existing_config = json.load(f) except Exception: pass # Start with empty config if read fails - - # Convert MCPServerConfig objects to dict + + # Use adapter for serialization (includes validation and field filtering) + adapter = get_adapter(self.get_adapter_host_name()) servers_dict = {} for name, server_config in config.servers.items(): - servers_dict[name] = server_config.model_dump(exclude_none=True) - + servers_dict[name] = adapter.serialize(server_config) + # Preserve Claude-specific settings - updated_config = self._preserve_claude_settings(existing_config, servers_dict) - + updated_config = self._preserve_claude_settings( + existing_config, servers_dict + ) + # Write atomically - temp_path = config_path.with_suffix('.tmp') - with open(temp_path, 'w') as f: + temp_path = config_path.with_suffix(".tmp") + with open(temp_path, "w") as f: json.dump(updated_config, f, indent=2) - + temp_path.replace(config_path) return True - + except Exception as e: logger.error(f"Failed to write Claude configuration: {e}") return False @@ -127,19 +143,31 @@ def write_configuration(self, config: HostConfiguration, no_backup: bool = False @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) class ClaudeDesktopStrategy(ClaudeHostStrategy): """Configuration strategy for Claude Desktop.""" - + def get_config_path(self) -> Optional[Path]: """Get Claude Desktop configuration path.""" system = platform.system() - + if system == "Darwin": # macOS - return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json" + return ( + Path.home() + / "Library" + / "Application Support" + / "Claude" + / "claude_desktop_config.json" + ) elif system == "Windows": - return Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json" + return ( + Path.home() + / "AppData" + / "Roaming" + / "Claude" + / "claude_desktop_config.json" + ) elif system == "Linux": return Path.home() / ".config" / "Claude" / "claude_desktop_config.json" return None - + def is_host_available(self) -> bool: """Check if Claude Desktop is installed.""" config_path = self.get_config_path() @@ -149,13 +177,17 @@ def is_host_available(self) -> bool: @register_host_strategy(MCPHostType.CLAUDE_CODE) class ClaudeCodeStrategy(ClaudeHostStrategy): """Configuration strategy for Claude for VS Code.""" - + + def get_adapter_host_name(self) -> str: + """Return the adapter host name for Claude Code.""" + return "claude-code" + def get_config_path(self) -> Optional[Path]: """Get Claude Code configuration path (workspace-specific).""" # Claude Code uses workspace-specific configuration # This would be determined at runtime based on current workspace return Path.home() / ".claude.json" - + def is_host_available(self) -> bool: """Check if Claude Code is available.""" # Check for Claude Code user configuration file @@ -165,15 +197,22 @@ def is_host_available(self) -> bool: class CursorBasedHostStrategy(MCPHostStrategy): """Base strategy for Cursor-based hosts (Cursor and LM Studio).""" - + def __init__(self): self.config_format = "cursor_format" self.supports_remote_servers = True - + + def get_adapter_host_name(self) -> str: + """Return the adapter host name for this strategy. + + Subclasses should override. Default is 'cursor'. + """ + return "cursor" + def get_config_key(self) -> str: """Cursor family uses 'mcpServers' key.""" return "mcpServers" - + def validate_server_config(self, server_config: MCPServerConfig) -> bool: """Cursor family validation - supports both local and remote servers.""" # Cursor family is more flexible with paths and supports remote servers @@ -182,11 +221,14 @@ def validate_server_config(self, server_config: MCPServerConfig) -> bool: elif server_config.url: return True # Remote server return False - + def _format_cursor_server_config(self, server_config: MCPServerConfig) -> Dict: - """Format server configuration for Cursor family.""" + """Format server configuration for Cursor family. + + DEPRECATED: Use adapter.serialize() instead. + """ config = {} - + if server_config.command: # Local server configuration config["command"] = server_config.command @@ -199,22 +241,22 @@ def _format_cursor_server_config(self, server_config: MCPServerConfig) -> Dict: config["url"] = server_config.url if server_config.headers: config["headers"] = server_config.headers - + return config - + def read_configuration(self) -> HostConfiguration: """Read Cursor-based configuration file.""" config_path = self.get_config_path() if not config_path or not config_path.exists(): return HostConfiguration() - + try: - with open(config_path, 'r') as f: + with open(config_path, "r") as f: config_data = json.load(f) - + # Extract MCP servers mcp_servers = config_data.get(self.get_config_key(), {}) - + # Convert to MCPServerConfig objects servers = {} for name, server_data in mcp_servers.items(): @@ -223,48 +265,51 @@ def read_configuration(self) -> HostConfiguration: except Exception as e: logger.warning(f"Invalid server config for {name}: {e}") continue - + return HostConfiguration(servers=servers) - + except Exception as e: logger.error(f"Failed to read Cursor configuration: {e}") return HostConfiguration() - - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write Cursor-based configuration file.""" + + def write_configuration( + self, config: HostConfiguration, no_backup: bool = False + ) -> bool: + """Write Cursor-based configuration file using adapter-based serialization.""" config_path = self.get_config_path() if not config_path: return False - + try: # Ensure parent directory exists config_path.parent.mkdir(parents=True, exist_ok=True) - + # Read existing configuration existing_config = {} if config_path.exists(): try: - with open(config_path, 'r') as f: + with open(config_path, "r") as f: existing_config = json.load(f) except Exception: pass - - # Convert MCPServerConfig objects to dict + + # Use adapter for serialization (includes validation and field filtering) + adapter = get_adapter(self.get_adapter_host_name()) servers_dict = {} for name, server_config in config.servers.items(): - servers_dict[name] = server_config.model_dump(exclude_none=True) - + servers_dict[name] = adapter.serialize(server_config) + # Update configuration existing_config[self.get_config_key()] = servers_dict - + # Write atomically - temp_path = config_path.with_suffix('.tmp') - with open(temp_path, 'w') as f: + temp_path = config_path.with_suffix(".tmp") + with open(temp_path, "w") as f: json.dump(existing_config, f, indent=2) - + temp_path.replace(config_path) return True - + except Exception as e: logger.error(f"Failed to write Cursor configuration: {e}") return False @@ -273,11 +318,11 @@ def write_configuration(self, config: HostConfiguration, no_backup: bool = False @register_host_strategy(MCPHostType.CURSOR) class CursorHostStrategy(CursorBasedHostStrategy): """Configuration strategy for Cursor IDE.""" - + def get_config_path(self) -> Optional[Path]: """Get Cursor configuration path.""" return Path.home() / ".cursor" / "mcp.json" - + def is_host_available(self) -> bool: """Check if Cursor IDE is installed.""" cursor_dir = Path.home() / ".cursor" @@ -287,14 +332,17 @@ def is_host_available(self) -> bool: @register_host_strategy(MCPHostType.LMSTUDIO) class LMStudioHostStrategy(CursorBasedHostStrategy): """Configuration strategy for LM Studio (follows Cursor format).""" - + + def get_adapter_host_name(self) -> str: + """Return the adapter host name for LM Studio.""" + return "lmstudio" + def get_config_path(self) -> Optional[Path]: """Get LM Studio configuration path.""" return Path.home() / ".lmstudio" / "mcp.json" - + def is_host_available(self) -> bool: """Check if LM Studio is installed.""" - config_path = self.get_config_path() return self.get_config_path().parent.exists() @@ -302,6 +350,10 @@ def is_host_available(self) -> bool: class VSCodeHostStrategy(MCPHostStrategy): """Configuration strategy for VS Code MCP extension with user-wide mcp support.""" + def get_adapter_host_name(self) -> str: + """Return the adapter host name for VS Code.""" + return "vscode" + def get_config_path(self) -> Optional[Path]: """Get VS Code user mcp configuration path (cross-platform).""" try: @@ -312,7 +364,14 @@ def get_config_path(self) -> Optional[Path]: return appdata / "Code" / "User" / "mcp.json" elif system == "Darwin": # macOS # macOS: $HOME/Library/Application Support/Code/User/mcp.json - return Path.home() / "Library" / "Application Support" / "Code" / "User" / "mcp.json" + return ( + Path.home() + / "Library" + / "Application Support" + / "Code" + / "User" + / "mcp.json" + ) elif system == "Linux": # Linux: $HOME/.config/Code/User/mcp.json return Path.home() / ".config" / "Code" / "User" / "mcp.json" @@ -343,7 +402,7 @@ def is_host_available(self) -> bool: def validate_server_config(self, server_config: MCPServerConfig) -> bool: """VS Code validation - flexible path handling.""" return server_config.command is not None or server_config.url is not None - + def read_configuration(self) -> HostConfiguration: """Read VS Code mcp.json configuration.""" config_path = self.get_config_path() @@ -351,7 +410,7 @@ def read_configuration(self) -> HostConfiguration: return HostConfiguration() try: - with open(config_path, 'r') as f: + with open(config_path, "r") as f: config_data = json.load(f) # Extract MCP servers from direct structure @@ -371,9 +430,11 @@ def read_configuration(self) -> HostConfiguration: except Exception as e: logger.error(f"Failed to read VS Code configuration: {e}") return HostConfiguration() - - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write VS Code mcp.json configuration.""" + + def write_configuration( + self, config: HostConfiguration, no_backup: bool = False + ) -> bool: + """Write VS Code mcp.json configuration using adapter-based serialization.""" config_path = self.get_config_path() if not config_path: return False @@ -386,22 +447,23 @@ def write_configuration(self, config: HostConfiguration, no_backup: bool = False existing_config = {} if config_path.exists(): try: - with open(config_path, 'r') as f: + with open(config_path, "r") as f: existing_config = json.load(f) except Exception: pass - # Convert MCPServerConfig objects to dict + # Use adapter for serialization (includes validation and field filtering) + adapter = get_adapter(self.get_adapter_host_name()) servers_dict = {} for name, server_config in config.servers.items(): - servers_dict[name] = server_config.model_dump(exclude_none=True) + servers_dict[name] = adapter.serialize(server_config) # Update configuration with new servers (preserves non-MCP settings) existing_config[self.get_config_key()] = servers_dict # Write atomically - temp_path = config_path.with_suffix('.tmp') - with open(temp_path, 'w') as f: + temp_path = config_path.with_suffix(".tmp") + with open(temp_path, "w") as f: json.dump(existing_config, f, indent=2) temp_path.replace(config_path) @@ -415,93 +477,100 @@ def write_configuration(self, config: HostConfiguration, no_backup: bool = False @register_host_strategy(MCPHostType.KIRO) class KiroHostStrategy(MCPHostStrategy): """Configuration strategy for Kiro IDE.""" - + + def get_adapter_host_name(self) -> str: + """Return the adapter host name for Kiro.""" + return "kiro" + def get_config_path(self) -> Optional[Path]: """Get Kiro configuration path (user-level only per constraint).""" return Path.home() / ".kiro" / "settings" / "mcp.json" - + def get_config_key(self) -> str: """Kiro uses 'mcpServers' key.""" return "mcpServers" - + def is_host_available(self) -> bool: """Check if Kiro is available by checking for settings directory.""" kiro_dir = Path.home() / ".kiro" / "settings" return kiro_dir.exists() - + def validate_server_config(self, server_config: MCPServerConfig) -> bool: """Kiro validation - supports both local and remote servers.""" return server_config.command is not None or server_config.url is not None - + def read_configuration(self) -> HostConfiguration: """Read Kiro configuration file.""" config_path_str = self.get_config_path() if not config_path_str: return HostConfiguration(servers={}) - + config_path = Path(config_path_str) if not config_path.exists(): return HostConfiguration(servers={}) - + try: - with open(config_path, 'r', encoding='utf-8') as f: + with open(config_path, "r", encoding="utf-8") as f: data = json.load(f) - + servers = {} mcp_servers = data.get(self.get_config_key(), {}) - + for name, config in mcp_servers.items(): try: servers[name] = MCPServerConfig(**config) except Exception as e: logger.warning(f"Invalid server config for {name}: {e}") continue - + return HostConfiguration(servers=servers) - + except Exception as e: logger.error(f"Failed to read Kiro configuration: {e}") return HostConfiguration(servers={}) - - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write configuration to Kiro with backup support.""" + + def write_configuration( + self, config: HostConfiguration, no_backup: bool = False + ) -> bool: + """Write configuration to Kiro with backup support using adapter-based serialization.""" config_path_str = self.get_config_path() if not config_path_str: return False - + config_path = Path(config_path_str) - + try: # Ensure directory exists config_path.parent.mkdir(parents=True, exist_ok=True) - + # Read existing configuration to preserve other settings existing_data = {} if config_path.exists(): - with open(config_path, 'r', encoding='utf-8') as f: + with open(config_path, "r", encoding="utf-8") as f: existing_data = json.load(f) - - # Update MCP servers section + + # Use adapter for serialization (includes validation and field filtering) + adapter = get_adapter(self.get_adapter_host_name()) servers_data = {} for name, server_config in config.servers.items(): - servers_data[name] = server_config.model_dump(exclude_unset=True) - + servers_data[name] = adapter.serialize(server_config) + existing_data[self.get_config_key()] = servers_data - + # Use atomic write with backup support backup_manager = MCPHostConfigBackupManager() atomic_ops = AtomicFileOperations() - + atomic_ops.atomic_write_with_backup( file_path=config_path, data=existing_data, backup_manager=backup_manager, hostname="kiro", - skip_backup=no_backup + skip_backup=no_backup, ) - + return True - + except Exception as e: logger.error(f"Failed to write Kiro configuration: {e}") return False @@ -510,40 +579,44 @@ def write_configuration(self, config: HostConfiguration, no_backup: bool = False @register_host_strategy(MCPHostType.GEMINI) class GeminiHostStrategy(MCPHostStrategy): """Configuration strategy for Google Gemini CLI MCP integration.""" - + + def get_adapter_host_name(self) -> str: + """Return the adapter host name for Gemini.""" + return "gemini" + def get_config_path(self) -> Optional[Path]: """Get Gemini configuration path based on official documentation.""" # Based on official Gemini CLI documentation: ~/.gemini/settings.json return Path.home() / ".gemini" / "settings.json" - + def get_config_key(self) -> str: """Gemini uses 'mcpServers' key in settings.json.""" return "mcpServers" - + def is_host_available(self) -> bool: """Check if Gemini CLI is available.""" # Check if Gemini CLI directory exists gemini_dir = Path.home() / ".gemini" return gemini_dir.exists() - + def validate_server_config(self, server_config: MCPServerConfig) -> bool: """Gemini validation - supports both local and remote servers.""" # Gemini CLI supports both command-based and URL-based servers return server_config.command is not None or server_config.url is not None - + def read_configuration(self) -> HostConfiguration: """Read Gemini settings.json configuration.""" config_path = self.get_config_path() if not config_path or not config_path.exists(): return HostConfiguration() - + try: - with open(config_path, 'r') as f: + with open(config_path, "r") as f: config_data = json.load(f) - + # Extract MCP servers from Gemini configuration mcp_servers = config_data.get(self.get_config_key(), {}) - + # Convert to MCPServerConfig objects servers = {} for name, server_data in mcp_servers.items(): @@ -552,15 +625,17 @@ def read_configuration(self) -> HostConfiguration: except Exception as e: logger.warning(f"Invalid server config for {name}: {e}") continue - + return HostConfiguration(servers=servers) - + except Exception as e: logger.error(f"Failed to read Gemini configuration: {e}") return HostConfiguration() - - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write Gemini settings.json configuration.""" + + def write_configuration( + self, config: HostConfiguration, no_backup: bool = False + ) -> bool: + """Write Gemini settings.json configuration using adapter-based serialization.""" config_path = self.get_config_path() if not config_path: return False @@ -573,27 +648,28 @@ def write_configuration(self, config: HostConfiguration, no_backup: bool = False existing_config = {} if config_path.exists(): try: - with open(config_path, 'r') as f: + with open(config_path, "r") as f: existing_config = json.load(f) except Exception: pass - # Convert MCPServerConfig objects to dict (REPLACE, don't merge) + # Use adapter for serialization (includes validation and field filtering) + adapter = get_adapter(self.get_adapter_host_name()) servers_dict = {} for name, server_config in config.servers.items(): - servers_dict[name] = server_config.model_dump(exclude_none=True) + servers_dict[name] = adapter.serialize(server_config) # Update configuration with new servers (preserves non-MCP settings) existing_config[self.get_config_key()] = servers_dict - + # Write atomically with enhanced error handling - temp_path = config_path.with_suffix('.tmp') + temp_path = config_path.with_suffix(".tmp") try: - with open(temp_path, 'w') as f: + with open(temp_path, "w") as f: json.dump(existing_config, f, indent=2, ensure_ascii=False) # Verify the JSON is valid by reading it back - with open(temp_path, 'r') as f: + with open(temp_path, "r") as f: json.load(f) # This will raise an exception if JSON is invalid # Only replace if verification succeeds @@ -605,7 +681,7 @@ def write_configuration(self, config: HostConfiguration, no_backup: bool = False temp_path.unlink() logger.error(f"JSON serialization/verification failed: {json_error}") raise - + except Exception as e: logger.error(f"Failed to write Gemini configuration: {e}") return False @@ -623,6 +699,10 @@ def __init__(self): self.config_format = "toml" self._preserved_features = {} # Preserve [features] section + def get_adapter_host_name(self) -> str: + """Return the adapter host name for Codex.""" + return "codex" + def get_config_path(self) -> Optional[Path]: """Get Codex configuration path.""" return Path.home() / ".codex" / "config.toml" @@ -647,11 +727,11 @@ def read_configuration(self) -> HostConfiguration: return HostConfiguration(servers={}) try: - with open(config_path, 'rb') as f: + with open(config_path, "rb") as f: toml_data = tomllib.load(f) # Preserve [features] section for later write - self._preserved_features = toml_data.get('features', {}) + self._preserved_features = toml_data.get("features", {}) # Extract MCP servers from [mcp_servers.*] tables mcp_servers = toml_data.get(self.get_config_key(), {}) @@ -672,8 +752,10 @@ def read_configuration(self) -> HostConfiguration: logger.error(f"Failed to read Codex configuration: {e}") return HostConfiguration(servers={}) - def write_configuration(self, config: HostConfiguration, no_backup: bool = False) -> bool: - """Write Codex TOML configuration file with backup support.""" + def write_configuration( + self, config: HostConfiguration, no_backup: bool = False + ) -> bool: + """Write Codex TOML configuration file with backup support using adapter-based serialization.""" config_path = self.get_config_path() if not config_path: return False @@ -685,33 +767,36 @@ def write_configuration(self, config: HostConfiguration, no_backup: bool = False existing_data = {} if config_path.exists(): try: - with open(config_path, 'rb') as f: + with open(config_path, "rb") as f: existing_data = tomllib.load(f) except Exception: pass # Preserve [features] section - if 'features' in existing_data: - self._preserved_features = existing_data['features'] + if "features" in existing_data: + self._preserved_features = existing_data["features"] - # Convert servers to TOML structure + # Use adapter for serialization (includes validation and field filtering) + adapter = get_adapter(self.get_adapter_host_name()) servers_data = {} for name, server_config in config.servers.items(): - servers_data[name] = self._to_toml_server(server_config) + # Adapter serializes and filters fields, then apply TOML-specific transforms + serialized = adapter.serialize(server_config) + servers_data[name] = self._to_toml_server_from_dict(serialized) # Build final TOML structure final_data = {} # Preserve [features] at top if self._preserved_features: - final_data['features'] = self._preserved_features + final_data["features"] = self._preserved_features # Add MCP servers final_data[self.get_config_key()] = servers_data # Preserve other top-level keys for key, value in existing_data.items(): - if key not in ('features', self.get_config_key()): + if key not in ("features", self.get_config_key()): final_data[key] = value # Use atomic write with TOML serializer @@ -729,7 +814,7 @@ def toml_serializer(data: Any, f: TextIO) -> None: serializer=toml_serializer, backup_manager=backup_manager, hostname="codex", - skip_backup=no_backup + skip_backup=no_backup, ) return True @@ -758,8 +843,8 @@ def _flatten_toml_server(self, server_data: Dict[str, Any]) -> Dict[str, Any]: data = dict(server_data) # Map Codex 'http_headers' to universal 'headers' for MCPServerConfig - if 'http_headers' in data: - data['headers'] = data.pop('http_headers') + if "http_headers" in data: + data["headers"] = data.pop("http_headers") return data @@ -771,10 +856,27 @@ def _to_toml_server(self, server_config: MCPServerConfig) -> Dict[str, Any]: data = server_config.model_dump(exclude_unset=True) # Remove 'name' field as it's the table key in TOML - data.pop('name', None) + data.pop("name", None) # Map universal 'headers' to Codex 'http_headers' for TOML - if 'headers' in data: - data['http_headers'] = data.pop('headers') + if "headers" in data: + data["http_headers"] = data.pop("headers") return data + + def _to_toml_server_from_dict(self, data: Dict[str, Any]) -> Dict[str, Any]: + """Apply TOML-specific transformations to an already-serialized dict. + + This is used after adapter serialization to apply Codex-specific field mappings. + Maps universal 'headers' field back to Codex-specific 'http_headers'. + """ + result = dict(data) + + # Remove 'name' field as it's the table key in TOML + result.pop("name", None) + + # Map universal 'headers' to Codex 'http_headers' for TOML + if "headers" in result: + result["http_headers"] = result.pop("headers") + + return result diff --git a/hatch/package_loader.py b/hatch/package_loader.py index 76d86d7..5ee3a33 100644 --- a/hatch/package_loader.py +++ b/hatch/package_loader.py @@ -15,12 +15,13 @@ class PackageLoaderError(Exception): """Exception raised for package loading errors.""" + pass class HatchPackageLoader: """Manages the downloading, caching, and installation of Hatch packages.""" - + def __init__(self, cache_dir: Optional[Path] = None): """Initialize the Hatch package loader. @@ -31,20 +32,20 @@ def __init__(self, cache_dir: Optional[Path] = None): """ self.logger = logging.getLogger("hatch.package_loader") self.logger.setLevel(logging.INFO) - + # Set up cache directory if cache_dir is None: - cache_dir = Path.home() / '.hatch' + cache_dir = Path.home() / ".hatch" self.cache_dir = cache_dir / "packages" self.cache_dir.mkdir(parents=True, exist_ok=True) - + def _get_package_path(self, package_name: str, version: str) -> Optional[Path]: """Get path to a cached package, if it exists. - + Args: package_name (str): Name of the package. version (str): Version of the package. - + Returns: Optional[Path]: Path to cached package or None if not cached. """ @@ -52,10 +53,16 @@ def _get_package_path(self, package_name: str, version: str) -> Optional[Path]: if pkg_path.exists() and pkg_path.is_dir(): return pkg_path return None - - def download_package(self, package_url: str, package_name: str, version: str, force_download: bool = False) -> Path: + + def download_package( + self, + package_url: str, + package_name: str, + version: str, + force_download: bool = False, + ) -> Path: """Download a package from a URL and cache it. - + This method handles the complete download process including: 1. Checking if the package is already cached 2. Creating a temporary directory for download @@ -63,21 +70,21 @@ def download_package(self, package_url: str, package_name: str, version: str, fo 4. Extracting the zip file 5. Validating the package structure 6. Moving the package to the cache directory - + When force_download is True, the method will always download the package directly from the source, even if it's already cached. This is useful when you want to ensure you have the latest version of a package. When used with registry refresh, it ensures both the package metadata and the actual package content are up to date. - + Args: package_url (str): URL to download the package from. package_name (str): Name of the package. version (str): Version of the package. force_download (bool, optional): Force download even if package is cached. Defaults to False. - + Returns: Path: Path to the downloaded package directory. - + Raises: PackageLoaderError: If download or extraction fails. """ @@ -86,154 +93,181 @@ def download_package(self, package_url: str, package_name: str, version: str, fo if cached_path and not force_download: self.logger.info(f"Using cached package {package_name} v{version}") return cached_path - + if cached_path and force_download: - self.logger.info(f"Force download requested. Downloading {package_name} v{version} from {package_url}") - + self.logger.info( + f"Force download requested. Downloading {package_name} v{version} from {package_url}" + ) + # Create temporary directory for download with tempfile.TemporaryDirectory() as temp_dir: temp_dir_path = Path(temp_dir) temp_file = temp_dir_path / f"{package_name}-{version}.zip" - + try: # Download the package self.logger.info(f"Downloading package from {package_url}") # Remote URL - download using requests response = requests.get(package_url, stream=True, timeout=30) response.raise_for_status() - - with open(temp_file, 'wb') as f: + + with open(temp_file, "wb") as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) - + # Extract the package extract_dir = temp_dir_path / f"{package_name}-{version}" extract_dir.mkdir(parents=True, exist_ok=True) - - with zipfile.ZipFile(temp_file, 'r') as zip_ref: + + with zipfile.ZipFile(temp_file, "r") as zip_ref: zip_ref.extractall(extract_dir) - + # Ensure expected package structure if not (extract_dir / "hatch_metadata.json").exists(): # Check if the package has a top-level directory subdirs = [d for d in extract_dir.iterdir() if d.is_dir()] - if len(subdirs) == 1 and (subdirs[0] / "hatch_metadata.json").exists(): + if ( + len(subdirs) == 1 + and (subdirs[0] / "hatch_metadata.json").exists() + ): # Use the top-level directory as the package extract_dir = subdirs[0] else: - raise PackageLoaderError(f"Invalid package structure: hatch_metadata.json not found") - + raise PackageLoaderError( + "Invalid package structure: hatch_metadata.json not found" + ) + # Create the cache directory cache_package_dir = self.cache_dir / f"{package_name}-{version}" if cache_package_dir.exists(): shutil.rmtree(cache_package_dir) - + # Move to cache shutil.copytree(extract_dir, cache_package_dir) - self.logger.info(f"Cached package {package_name} v{version} to {cache_package_dir}") - + self.logger.info( + f"Cached package {package_name} v{version} to {cache_package_dir}" + ) + return cache_package_dir - + except requests.RequestException as e: raise PackageLoaderError(f"Failed to download package: {e}") except zipfile.BadZipFile: raise PackageLoaderError("Downloaded file is not a valid zip archive") except Exception as e: raise PackageLoaderError(f"Error downloading package: {e}") - + def copy_package(self, source_path: Path, target_path: Path) -> bool: """Copy a package from source to target directory. - + Args: source_path (Path): Source directory path. target_path (Path): Target directory path. - + Returns: bool: True if successful. - + Raises: PackageLoaderError: If copy fails. """ try: if target_path.exists(): shutil.rmtree(target_path) - + shutil.copytree(source_path, target_path) return True except Exception as e: raise PackageLoaderError(f"Failed to copy package: {e}") - - def install_local_package(self, source_path: Path, target_dir: Path, package_name: str) -> Path: + + def install_local_package( + self, source_path: Path, target_dir: Path, package_name: str + ) -> Path: """Install a local package to the target directory. - + Args: source_path (Path): Path to the source package directory. target_dir (Path): Directory to install the package to. package_name (str): Name of the package for the target directory. - + Returns: Path: Path to the installed package. - + Raises: PackageLoaderError: If installation fails. """ target_path = target_dir / package_name - + try: self.copy_package(source_path, target_path) - self.logger.info(f"Installed local package: {package_name} to {target_path}") + self.logger.info( + f"Installed local package: {package_name} to {target_path}" + ) return target_path except Exception as e: raise PackageLoaderError(f"Failed to install local package: {e}") - - def install_remote_package(self, package_url: str, package_name: str, - version: str, target_dir: Path, force_download: bool = False) -> Path: + + def install_remote_package( + self, + package_url: str, + package_name: str, + version: str, + target_dir: Path, + force_download: bool = False, + ) -> Path: """Download and install a remote package. - + This method handles downloading a package from a remote URL and installing it into the specified target directory. It leverages the download_package method which includes caching functionality, but allows forcing a fresh download when needed. - + Args: package_url (str): URL to download the package from. package_name (str): Name of the package. version (str): Version of the package. target_dir (Path): Directory to install the package to. force_download (bool, optional): Force download even if package is cached. Defaults to False. - + Returns: Path: Path to the installed package. - + Raises: PackageLoaderError: If installation fails. """ try: - cached_path = self.download_package(package_url, package_name, version, force_download) + cached_path = self.download_package( + package_url, package_name, version, force_download + ) # Install from cache to target dir target_path = target_dir / package_name - + # Remove existing installation if it exists if target_path.exists(): self.logger.info(f"Removing existing package at {target_path}") shutil.rmtree(target_path) - + # Copy package to target self.copy_package(cached_path, target_path) - - self.logger.info(f"Successfully installed package {package_name} v{version} to {target_path}") + + self.logger.info( + f"Successfully installed package {package_name} v{version} to {target_path}" + ) return target_path - + except Exception as e: - raise PackageLoaderError(f"Failed to install remote package {package_name} from {package_url}: {e}") - - def clear_cache(self, package_name: Optional[str] = None, version: Optional[str] = None) -> bool: + raise PackageLoaderError( + f"Failed to install remote package {package_name} from {package_url}: {e}" + ) + + def clear_cache( + self, package_name: Optional[str] = None, version: Optional[str] = None + ) -> bool: """Clear the package cache. - + Args: package_name (str, optional): Name of specific package to clear. Defaults to None (all packages). version (str, optional): Version of specific package to clear. Defaults to None (all versions). - + Returns: bool: True if successful. """ @@ -256,8 +290,8 @@ def clear_cache(self, package_name: Optional[str] = None, version: Optional[str] if path.is_dir(): shutil.rmtree(path) self.logger.info("Cleared entire package cache") - + return True except Exception as e: self.logger.error(f"Failed to clear cache: {e}") - return False \ No newline at end of file + return False diff --git a/hatch/python_environment_manager.py b/hatch/python_environment_manager.py index 256d467..5b4936d 100644 --- a/hatch/python_environment_manager.py +++ b/hatch/python_environment_manager.py @@ -13,17 +13,18 @@ import sys import os from pathlib import Path -from typing import Dict, List, Optional, Tuple, Any +from typing import Dict, List, Optional, Any class PythonEnvironmentError(Exception): """Exception raised for Python environment-related errors.""" + pass class PythonEnvironmentManager: """Manages Python environments using conda/mamba for cross-platform isolation. - + This class handles: 1. Creating and managing named conda/mamba environments 2. Python version management and executable path resolution @@ -31,32 +32,36 @@ class PythonEnvironmentManager: 4. Environment lifecycle operations (create, remove, info) 5. Integration with InstallationContext for Python executable configuration """ - + def __init__(self, environments_dir: Optional[Path] = None): """Initialize the Python environment manager. - + Args: environments_dir (Path, optional): Directory where Hatch environments are stored. Defaults to ~/.hatch/envs. """ self.logger = logging.getLogger("hatch.python_environment_manager") self.logger.setLevel(logging.INFO) - + # Set up environment directories self.environments_dir = environments_dir or (Path.home() / ".hatch" / "envs") - + # Detect available conda/mamba self.conda_executable = None self.mamba_executable = None self._detect_conda_mamba() - - self.logger.debug(f"Python environment manager initialized with environments_dir: {self.environments_dir}") + + self.logger.debug( + f"Python environment manager initialized with environments_dir: {self.environments_dir}" + ) if self.mamba_executable: self.logger.debug(f"Using mamba: {self.mamba_executable}") elif self.conda_executable: self.logger.debug(f"Using conda: {self.conda_executable}") else: - self.logger.warning("Neither conda nor mamba found - Python environment management will be limited") + self.logger.warning( + "Neither conda nor mamba found - Python environment management will be limited" + ) def _detect_manager(self, manager: str) -> Optional[str]: """Detect the given manager ('mamba' or 'conda') executable on the system. @@ -70,6 +75,7 @@ def _detect_manager(self, manager: str) -> Optional[str]: Returns: Optional[str]: The path to the detected executable, or None if not found. """ + def find_in_common_paths(names): paths = [] if platform.system() == "Windows": @@ -108,16 +114,15 @@ def find_in_common_paths(names): self.logger.debug(f"Trying to detect {manager} at: {path}") try: result = subprocess.run( - [path, "--version"], - capture_output=True, - text=True, - timeout=10 + [path, "--version"], capture_output=True, text=True, timeout=10 ) if result.returncode == 0: self.logger.debug(f"Detected {manager} at: {path}") return path except Exception as e: - self.logger.warning(f"{manager.capitalize()} not found or not working at {path}: {e}") + self.logger.warning( + f"{manager.capitalize()} not found or not working at {path}: {e}" + ) return None def _detect_conda_mamba(self) -> None: @@ -131,7 +136,7 @@ def _detect_conda_mamba(self) -> None: def is_available(self) -> bool: """Check if Python environment management is available. - + Returns: bool: True if conda/mamba is available and functional, False otherwise. """ @@ -141,7 +146,7 @@ def is_available(self) -> bool: def get_preferred_executable(self) -> Optional[str]: """Get the preferred conda/mamba executable. - + Returns: str: Path to mamba (preferred) or conda executable, None if neither available. """ @@ -149,72 +154,75 @@ def get_preferred_executable(self) -> Optional[str]: def _get_conda_env_name(self, env_name: str) -> str: """Get the conda environment name for a Hatch environment. - + Args: env_name (str): Hatch environment name. - + Returns: str: Conda environment name following the hatch_ pattern. """ return f"hatch_{env_name}" - def create_python_environment(self, env_name: str, python_version: Optional[str] = None, - force: bool = False) -> bool: + def create_python_environment( + self, env_name: str, python_version: Optional[str] = None, force: bool = False + ) -> bool: """Create a Python environment using conda/mamba. - + Creates a named conda environment with the specified Python version. - + Args: env_name (str): Hatch environment name. python_version (str, optional): Python version to install (e.g., "3.11", "3.12"). If None, uses the default Python version from conda. force (bool, optional): Whether to force recreation if environment exists. Defaults to False. - + Returns: bool: True if environment was created successfully, False otherwise. - + Raises: PythonEnvironmentError: If conda/mamba is not available or creation fails. """ if not self.is_available(): - raise PythonEnvironmentError("Neither conda nor mamba is available for Python environment management") - + raise PythonEnvironmentError( + "Neither conda nor mamba is available for Python environment management" + ) + executable = self.get_preferred_executable() env_name_conda = self._get_conda_env_name(env_name) conda_env_exists = self._conda_env_exists(env_name) - + # Check if environment already exists if conda_env_exists and not force: self.logger.warning(f"Python environment already exists for {env_name}") return True - + # Remove existing environment if force is True if force and conda_env_exists: self.logger.info(f"Removing existing Python environment for {env_name}") self.remove_python_environment(env_name) - + # Build conda create command cmd = [executable, "create", "--yes", "--name", env_name_conda] - + if python_version: cmd.extend(["python=" + python_version]) else: cmd.append("python") - + try: - self.logger.debug(f"Creating Python environment for {env_name} with name {env_name_conda}") + self.logger.debug( + f"Creating Python environment for {env_name} with name {env_name_conda}" + ) if python_version: self.logger.debug(f"Using Python version: {python_version}") - result = subprocess.run( - cmd - ) - + result = subprocess.run(cmd) + if result.returncode == 0: return True else: - error_msg = f"Failed to create Python environment (see terminal output)" + error_msg = "Failed to create Python environment (see terminal output)" self.logger.error(error_msg) raise PythonEnvironmentError(error_msg) @@ -225,67 +233,72 @@ def create_python_environment(self, env_name: str, python_version: Optional[str] def _conda_env_exists(self, env_name: str) -> bool: """Check if a conda environment exists for the given Hatch environment. - + Args: env_name (str): Hatch environment name. - + Returns: bool: True if the conda environment exists, False otherwise. """ if not self.is_available(): return False - + executable = self.get_preferred_executable() env_name_conda = self._get_conda_env_name(env_name) - + try: # Use conda env list to check if the environment exists result = subprocess.run( [executable, "env", "list", "--json"], capture_output=True, text=True, - timeout=30 + timeout=30, ) - + if result.returncode == 0: import json + envs_data = json.loads(result.stdout) env_names = [Path(env).name for env in envs_data.get("envs", [])] return env_name_conda in env_names else: return False - - except (subprocess.TimeoutExpired, subprocess.SubprocessError, json.JSONDecodeError): + + except ( + subprocess.TimeoutExpired, + subprocess.SubprocessError, + json.JSONDecodeError, + ): return False def _get_python_executable_path(self, env_name: str) -> Optional[Path]: """Get the Python executable path for a given environment. - + Args: env_name (str): Hatch environment name. - + Returns: Path: Path to the Python executable in the environment, None if not found. """ if not self.is_available(): return None - + executable = self.get_preferred_executable() env_name_conda = self._get_conda_env_name(env_name) - + try: # Get environment info to find the prefix path result = subprocess.run( [executable, "info", "--envs", "--json"], capture_output=True, text=True, - timeout=30 + timeout=30, ) - + if result.returncode == 0: envs_data = json.loads(result.stdout) envs = envs_data.get("envs", []) - + # Find the environment path for env_path in envs: if Path(env_path).name == env_name_conda: @@ -293,66 +306,72 @@ def _get_python_executable_path(self, env_name: str) -> Optional[Path]: return Path(env_path) / "python.exe" else: return Path(env_path) / "bin" / "python" - + return None - - except (subprocess.TimeoutExpired, subprocess.SubprocessError, json.JSONDecodeError): + + except ( + subprocess.TimeoutExpired, + subprocess.SubprocessError, + json.JSONDecodeError, + ): return None def get_python_executable(self, env_name: str) -> Optional[str]: """Get the Python executable path for an environment if it exists. - + Args: env_name (str): Hatch environment name. - + Returns: str: Path to Python executable if environment exists, None otherwise. """ if not self._conda_env_exists(env_name): return None - + python_path = self._get_python_executable_path(env_name) return str(python_path) if python_path and python_path.exists() else None def remove_python_environment(self, env_name: str) -> bool: """Remove a Python environment. - + Args: env_name (str): Hatch environment name. - + Returns: bool: True if environment was removed successfully, False otherwise. - + Raises: PythonEnvironmentError: If conda/mamba is not available or removal fails. """ if not self.is_available(): - raise PythonEnvironmentError("Neither conda nor mamba is available for Python environment management") - + raise PythonEnvironmentError( + "Neither conda nor mamba is available for Python environment management" + ) + if not self._conda_env_exists(env_name): self.logger.warning(f"Python environment does not exist for {env_name}") return True - + executable = self.get_preferred_executable() env_name_conda = self._get_conda_env_name(env_name) - + try: self.logger.info(f"Removing Python environment for {env_name}") - + # Use conda/mamba remove with --name # Show output in terminal by not capturing output result = subprocess.run( [executable, "env", "remove", "--yes", "--name", env_name_conda], - timeout=120 # 2 minutes timeout + timeout=120, # 2 minutes timeout ) - - if result.returncode == 0: + + if result.returncode == 0: return True else: - error_msg = f"Failed to remove Python environment: (see terminal output)" + error_msg = "Failed to remove Python environment: (see terminal output)" self.logger.error(error_msg) raise PythonEnvironmentError(error_msg) - + except subprocess.TimeoutExpired: error_msg = f"Timeout removing Python environment for {env_name}" self.logger.error(error_msg) @@ -364,21 +383,21 @@ def remove_python_environment(self, env_name: str) -> bool: def get_environment_info(self, env_name: str) -> Optional[Dict[str, Any]]: """Get information about a Python environment. - + Args: env_name (str): Hatch environment name. - + Returns: dict: Environment information including Python version, packages, etc. None if environment doesn't exist. """ if not self._conda_env_exists(env_name): return None - + executable = self.get_preferred_executable() env_name_conda = self._get_conda_env_name(env_name) python_executable = self._get_python_executable_path(env_name) - + info = { "environment_name": env_name, "conda_env_name": env_name_conda, @@ -386,9 +405,9 @@ def get_environment_info(self, env_name: str) -> Optional[Dict[str, Any]]: "python_executable": str(python_executable) if python_executable else None, "python_version": self.get_python_version(env_name), "exists": True, - "platform": platform.system() + "platform": platform.system(), } - + # Get conda environment info if self.is_available(): try: @@ -396,71 +415,79 @@ def get_environment_info(self, env_name: str) -> Optional[Dict[str, Any]]: [executable, "list", "--name", env_name_conda, "--json"], capture_output=True, text=True, - timeout=30 + timeout=30, ) if result.returncode == 0: packages = json.loads(result.stdout) info["packages"] = packages info["package_count"] = len(packages) - except (subprocess.TimeoutExpired, subprocess.SubprocessError, json.JSONDecodeError): + except ( + subprocess.TimeoutExpired, + subprocess.SubprocessError, + json.JSONDecodeError, + ): info["packages"] = [] info["package_count"] = 0 - + return info def list_environments(self) -> List[str]: """List all Python environments managed by this manager. - + Returns: list: List of environment names that have Python environments. """ environments = [] - + if not self.is_available(): return environments - + executable = self.get_preferred_executable() - + try: result = subprocess.run( [executable, "env", "list", "--json"], capture_output=True, text=True, - timeout=30 + timeout=30, ) - + if result.returncode == 0: envs_data = json.loads(result.stdout) env_paths = envs_data.get("envs", []) - + # Filter for hatch environments for env_path in env_paths: environments.append(Path(env_path).name) - - except (subprocess.TimeoutExpired, subprocess.SubprocessError, json.JSONDecodeError): + + except ( + subprocess.TimeoutExpired, + subprocess.SubprocessError, + json.JSONDecodeError, + ): pass - + return environments def get_python_version(self, env_name: str) -> Optional[str]: """Get the Python version for an environment. - + Args: env_name (str): Hatch environment name. - + Returns: str: Python version if environment exists, None otherwise. """ python_executable = self.get_python_executable(env_name) if not python_executable: return None - + try: result = subprocess.run( [python_executable, "--version"], capture_output=True, text=True, - timeout=10 + timeout=10, ) if result.returncode == 0: # Parse version from "Python X.Y.Z" format @@ -470,42 +497,44 @@ def get_python_version(self, env_name: str) -> Optional[str]: return version_line except (subprocess.TimeoutExpired, subprocess.SubprocessError): pass - + return None - def get_environment_activation_info(self, env_name: str) -> Optional[Dict[str, str]]: + def get_environment_activation_info( + self, env_name: str + ) -> Optional[Dict[str, str]]: """Get environment variables needed to activate a Python environment. - + This method returns the environment variables that should be set to properly activate the Python environment, but doesn't actually modify the current process environment. This can typically be used when running subprocesses or in shell scripts to set up the environment. - + Args: env_name (str): Hatch environment name. - + Returns: dict: Environment variables to set for activation, None if env doesn't exist. """ if not self._conda_env_exists(env_name): return None - + env_name_conda = self._get_conda_env_name(env_name) python_executable = self._get_python_executable_path(env_name) - + if not python_executable: return None - + env_vars = {} - + # Set CONDA_DEFAULT_ENV to the environment name env_vars["CONDA_DEFAULT_ENV"] = env_name_conda - + # Get the actual environment path from conda env_path = self.get_environment_path(env_name) if env_path: env_vars["CONDA_PREFIX"] = str(env_path) - + # Update PATH to include environment's bin/Scripts directory if platform.system() == "Windows": scripts_dir = env_path / "Scripts" @@ -514,38 +543,42 @@ def get_environment_activation_info(self, env_name: str) -> Optional[Dict[str, s else: bin_dir = env_path / "bin" bin_paths = [str(bin_dir)] - + # Get current PATH and prepend environment paths current_path = os.environ.get("PATH", "") new_path = os.pathsep.join(bin_paths + [current_path]) env_vars["PATH"] = new_path - + # Set PYTHON environment variable env_vars["PYTHON"] = str(python_executable) - + return env_vars def get_manager_info(self) -> Dict[str, Any]: """Get information about the Python environment manager capabilities. - + Returns: dict: Manager information including available executables and status. """ return { "conda_executable": self.conda_executable, "mamba_executable": self.mamba_executable, - "preferred_manager": self.mamba_executable if self.mamba_executable else self.conda_executable, + "preferred_manager": ( + self.mamba_executable + if self.mamba_executable + else self.conda_executable + ), "is_available": self.is_available(), "platform": platform.system(), - "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}" + "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}", } - + def get_environment_diagnostics(self, env_name: str) -> Dict[str, Any]: """Get detailed diagnostics for a specific Python environment. - + Args: env_name (str): Environment name. - + Returns: dict: Detailed diagnostics information. """ @@ -555,48 +588,50 @@ def get_environment_diagnostics(self, env_name: str) -> Dict[str, Any]: "exists": False, "conda_available": self.is_available(), "manager_executable": self.mamba_executable or self.conda_executable, - "platform": platform.system() + "platform": platform.system(), } - + # Check if environment exists if self.environment_exists(env_name): diagnostics["exists"] = True - + # Get Python executable python_exec = self.get_python_executable(env_name) diagnostics["python_executable"] = python_exec diagnostics["python_accessible"] = python_exec is not None - + # Get Python version if python_exec: python_version = self.get_python_version(env_name) diagnostics["python_version"] = python_version diagnostics["python_version_accessible"] = python_version is not None - + # Check if executable actually works try: result = subprocess.run( [python_exec, "--version"], capture_output=True, text=True, - timeout=10 + timeout=10, ) diagnostics["python_executable_works"] = result.returncode == 0 diagnostics["python_version_output"] = result.stdout.strip() except Exception as e: diagnostics["python_executable_works"] = False diagnostics["python_executable_error"] = str(e) - + # Get environment path env_path = self.get_environment_path(env_name) diagnostics["environment_path"] = str(env_path) if env_path else None - diagnostics["environment_path_exists"] = env_path.exists() if env_path else False - + diagnostics["environment_path_exists"] = ( + env_path.exists() if env_path else False + ) + return diagnostics - + def get_manager_diagnostics(self) -> Dict[str, Any]: """Get general diagnostics for the Python environment manager. - + Returns: dict: General manager diagnostics. """ @@ -606,129 +641,134 @@ def get_manager_diagnostics(self) -> Dict[str, Any]: "conda_available": self.conda_executable is not None, "mamba_available": self.mamba_executable is not None, "any_manager_available": self.is_available(), - "preferred_manager": self.mamba_executable if self.mamba_executable else self.conda_executable, + "preferred_manager": ( + self.mamba_executable + if self.mamba_executable + else self.conda_executable + ), "platform": platform.system(), "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}", - "environments_dir": str(self.environments_dir) + "environments_dir": str(self.environments_dir), } - + # Test conda/mamba executables - for manager_name, executable in [("conda", self.conda_executable), ("mamba", self.mamba_executable)]: + for manager_name, executable in [ + ("conda", self.conda_executable), + ("mamba", self.mamba_executable), + ]: if executable: try: result = subprocess.run( [executable, "--version"], capture_output=True, text=True, - timeout=10 + timeout=10, ) diagnostics[f"{manager_name}_works"] = result.returncode == 0 diagnostics[f"{manager_name}_version"] = result.stdout.strip() except Exception as e: diagnostics[f"{manager_name}_works"] = False diagnostics[f"{manager_name}_error"] = str(e) - + return diagnostics - + def launch_shell(self, env_name: str, cmd: Optional[str] = None) -> bool: """Launch a Python shell or execute a command in the environment. - + Args: env_name (str): Environment name. cmd (str, optional): Command to execute. If None, launches interactive shell. - + Returns: bool: True if successful, False otherwise. """ if not self.environment_exists(env_name): self.logger.error(f"Environment {env_name} does not exist") return False - + python_exec = self.get_python_executable(env_name) if not python_exec: self.logger.error(f"Python executable not found for environment {env_name}") return False - + try: if cmd: # Execute specific command self.logger.info(f"Executing command in {env_name}: {cmd}") - result = subprocess.run( - [python_exec, "-c", cmd], - cwd=os.getcwd() - ) + result = subprocess.run([python_exec, "-c", cmd], cwd=os.getcwd()) return result.returncode == 0 else: # Launch interactive shell self.logger.info(f"Launching Python shell for environment {env_name}") self.logger.info(f"Python executable: {python_exec}") - + # On Windows, we need to activate the conda environment first if platform.system() == "Windows": env_name_conda = self._get_conda_env_name(env_name) activate_cmd = f"{self.get_preferred_executable()} activate {env_name_conda} && python" result = subprocess.run( - ["cmd", "/c", activate_cmd], - cwd=os.getcwd() + ["cmd", "/c", activate_cmd], cwd=os.getcwd() ) else: # On Unix-like systems, we can directly use the Python executable - result = subprocess.run( - [python_exec], - cwd=os.getcwd() - ) - + result = subprocess.run([python_exec], cwd=os.getcwd()) + return result.returncode == 0 - + except Exception as e: self.logger.error(f"Failed to launch shell for {env_name}: {e}") return False def environment_exists(self, env_name: str) -> bool: """Check if a Python environment exists. - + Args: env_name (str): Environment name. - + Returns: bool: True if environment exists, False otherwise. """ return self._conda_env_exists(env_name) - + def get_environment_path(self, env_name: str) -> Optional[Path]: """Get the actual filesystem path for a conda environment. - + Args: env_name (str): Hatch environment name. - + Returns: Path: Path to the conda environment directory, None if not found. """ if not self.is_available(): return None - + executable = self.get_preferred_executable() env_name_conda = self._get_conda_env_name(env_name) - + try: result = subprocess.run( [executable, "info", "--envs", "--json"], capture_output=True, text=True, - timeout=30 + timeout=30, ) - + if result.returncode == 0: import json + envs_data = json.loads(result.stdout) envs = envs_data.get("envs", []) - + # Find the environment path for env_path in envs: if Path(env_path).name == env_name_conda: return Path(env_path) - + return None - - except (subprocess.TimeoutExpired, subprocess.SubprocessError, json.JSONDecodeError): + + except ( + subprocess.TimeoutExpired, + subprocess.SubprocessError, + json.JSONDecodeError, + ): return None diff --git a/hatch/registry_explorer.py b/hatch/registry_explorer.py index f082458..727c93d 100644 --- a/hatch/registry_explorer.py +++ b/hatch/registry_explorer.py @@ -3,17 +3,21 @@ This module provides functions to search and extract information from a Hatch registry data structure (see hatch_all_pkg_metadata_schema.json). """ + from typing import Any, Dict, List, Optional, Tuple from packaging.version import Version, InvalidVersion from packaging.specifiers import SpecifierSet, InvalidSpecifier -def find_repository(registry: Dict[str, Any], repo_name: str) -> Optional[Dict[str, Any]]: + +def find_repository( + registry: Dict[str, Any], repo_name: str +) -> Optional[Dict[str, Any]]: """Find a repository by name. - + Args: registry (Dict[str, Any]): The registry data. repo_name (str): Name of the repository to find. - + Returns: Optional[Dict[str, Any]]: Repository data if found, None otherwise. """ @@ -22,25 +26,29 @@ def find_repository(registry: Dict[str, Any], repo_name: str) -> Optional[Dict[s return repo return None + def list_repositories(registry: Dict[str, Any]) -> List[str]: """List all repository names in the registry. - + Args: registry (Dict[str, Any]): The registry data. - + Returns: List[str]: List of repository names. """ return [repo.get("name") for repo in registry.get("repositories", [])] -def find_package(registry: Dict[str, Any], package_name: str, repo_name: Optional[str] = None) -> Optional[Dict[str, Any]]: + +def find_package( + registry: Dict[str, Any], package_name: str, repo_name: Optional[str] = None +) -> Optional[Dict[str, Any]]: """Find a package by name, optionally within a specific repository. - + Args: registry (Dict[str, Any]): The registry data. package_name (str): Name of the package to find. repo_name (str, optional): Name of the repository to search in. Defaults to None. - + Returns: Optional[Dict[str, Any]]: Package data if found, None otherwise. """ @@ -53,13 +61,16 @@ def find_package(registry: Dict[str, Any], package_name: str, repo_name: Optiona return pkg return None -def list_packages(registry: Dict[str, Any], repo_name: Optional[str] = None) -> List[str]: + +def list_packages( + registry: Dict[str, Any], repo_name: Optional[str] = None +) -> List[str]: """List all package names, optionally within a specific repository. - + Args: registry (Dict[str, Any]): The registry data. repo_name (str, optional): Name of the repository to list packages from. Defaults to None. - + Returns: List[str]: List of package names. """ @@ -72,37 +83,41 @@ def list_packages(registry: Dict[str, Any], repo_name: Optional[str] = None) -> packages.append(pkg.get("name")) return packages + def get_latest_version(pkg: Dict[str, Any]) -> Optional[str]: """Get the latest version string for a package dict. - + Args: pkg (Dict[str, Any]): The package dictionary. - + Returns: Optional[str]: Latest version string if available, None otherwise. """ return pkg.get("latest_version") + def _match_version_constraint(version: str, constraint: str) -> bool: """Check if a version string matches a constraint. - + Uses the 'packaging' library for robust version comparison. If a simple version like "1.0.0" is passed as constraint, it's treated as "==1.0.0". - + Args: version (str): Version string to check. constraint (str): Version constraint (e.g., '>=1.2.0'). - + Returns: bool: True if version matches constraint, False otherwise. """ try: v = Version(version) - + # Convert the constraint to a proper SpecifierSet if it doesn't have an operator - if constraint and not any(constraint.startswith(op) for op in ['==', '!=', '<=', '>=', '<', '>']): + if constraint and not any( + constraint.startswith(op) for op in ["==", "!=", "<=", ">=", "<", ">"] + ): constraint = f"=={constraint}" - + # Accept constraints like '==1.2.3', '>=1.0.0', etc. spec = SpecifierSet(constraint) return v in spec @@ -110,14 +125,17 @@ def _match_version_constraint(version: str, constraint: str) -> bool: # If we can't parse versions, fall back to string comparison return version == constraint -def find_package_version(pkg: Dict[str, Any], version_constraint: Optional[str] = None) -> Optional[Dict[str, Any]]: + +def find_package_version( + pkg: Dict[str, Any], version_constraint: Optional[str] = None +) -> Optional[Dict[str, Any]]: """Find a version dict for a package, optionally matching a version constraint. - + This function uses a multi-step approach to find the appropriate version: 1. If no constraint is given, it returns the latest version 2. If that's not found, it falls back to the highest version number 3. For specific constraints, it sorts versions and checks compatibility - + Args: pkg (Dict[str, Any]): The package dictionary. version_constraint (str, optional): A version constraint string (e.g., '>=1.2.0'). Defaults to None. @@ -138,25 +156,30 @@ def find_package_version(pkg: Dict[str, Any], version_constraint: Optional[str] try: return max(versions, key=lambda x: Version(x.get("version", "0"))) except Exception: - return versions[-1] # Try to find a version matching the constraint + return versions[-1] # Try to find a version matching the constraint try: - sorted_versions = sorted(versions, key=lambda x: Version(x.get("version", "0")), reverse=True) + sorted_versions = sorted( + versions, key=lambda x: Version(x.get("version", "0")), reverse=True + ) except Exception: - sorted_versions = versions - + sorted_versions = versions + # If no exact match, try parsing as a constraint for v in sorted_versions: if _match_version_constraint(v.get("version", ""), version_constraint): return v return None -def get_package_release_url(pkg: Dict[str, Any], version_constraint: Optional[str] = None) -> Tuple[Optional[str], Optional[str]]: + +def get_package_release_url( + pkg: Dict[str, Any], version_constraint: Optional[str] = None +) -> Tuple[Optional[str], Optional[str]]: """Get the release URI for a package version matching the constraint (or latest). Args: pkg (Dict[str, Any]): The package dictionary. version_constraint (str, optional): A version constraint string (e.g., '>=1.2.0'). Defaults to None. - + Returns: Tuple[Optional[str], Optional[str]]: A tuple containing: - str: The release URI satisfying the constraint (or None) diff --git a/hatch/registry_retriever.py b/hatch/registry_retriever.py index 74bae79..d905484 100644 --- a/hatch/registry_retriever.py +++ b/hatch/registry_retriever.py @@ -4,188 +4,208 @@ supporting both online and simulation modes with caching at file system and in-memory levels. """ -import os import json import logging import requests -import hashlib -import time import datetime from pathlib import Path -from typing import Dict, Any, Optional, Tuple, Union -from urllib.parse import urlparse +from typing import Dict, Any, Optional + class RegistryRetriever: """Manages the retrieval and caching of the Hatch package registry. - + Provides caching at file system level and in-memory level with persistent timestamp tracking for cache freshness across CLI invocations. Works in both local simulation and online GitHub environments. Handles registry timing issues with fallback to previous day's registry. """ - + def __init__( - self, + self, cache_ttl: int = 86400, # Default TTL is 24 hours local_cache_dir: Optional[Path] = None, simulation_mode: bool = False, # Set to True when running in local simulation mode - local_registry_cache_path: Optional[Path] = None + local_registry_cache_path: Optional[Path] = None, ): """Initialize the registry retriever. - + Args: cache_ttl (int): Time-to-live for cache in seconds. Defaults to 86400 (24 hours). local_cache_dir (Path, optional): Directory to store local cache files. Defaults to ~/.hatch. simulation_mode (bool): Whether to operate in local simulation mode. Defaults to False. local_registry_cache_path (Path, optional): Path to local registry file. Defaults to None. """ - self.logger = logging.getLogger('hatch.registry_retriever') + self.logger = logging.getLogger("hatch.registry_retriever") self.logger.setLevel(logging.INFO) self.cache_ttl = cache_ttl self.simulation_mode = simulation_mode self.is_delayed = False # Flag to indicate if using a previous day's registry - + # Initialize cache directory self.cache_dir = local_cache_dir or Path.home() / ".hatch" - + # Create cache directory if it doesn't exist - self.cache_dir.mkdir(parents=True, exist_ok=True) # Set up registry source based on mode + self.cache_dir.mkdir( + parents=True, exist_ok=True + ) # Set up registry source based on mode if simulation_mode: # Local simulation mode - use local registry file - self.registry_cache_path = local_registry_cache_path or self.cache_dir / "registry" / "hatch_packages_registry.json" - + self.registry_cache_path = ( + local_registry_cache_path + or self.cache_dir / "registry" / "hatch_packages_registry.json" + ) + # Use file:// URL format for local files self.registry_url = f"file://{str(self.registry_cache_path.absolute())}" - self.logger.info(f"Operating in simulation mode with registry at: {self.registry_cache_path}") + self.logger.info( + f"Operating in simulation mode with registry at: {self.registry_cache_path}" + ) else: # Online mode - set today's date as the default target self.today_date = datetime.datetime.now(datetime.timezone.utc).date() - self.today_str = self.today_date.strftime('%Y-%m-%d') - + self.today_str = self.today_date.strftime("%Y-%m-%d") + # We'll set the initial URL to today, but might fall back to yesterday self.registry_url = f"https://github.com/CrackingShells/Hatch-Registry/releases/download/{self.today_str}/hatch_packages_registry.json" - self.logger.info(f"Operating in online mode with registry at: {self.registry_url}") - + self.logger.info( + f"Operating in online mode with registry at: {self.registry_url}" + ) + # Generate cache filename - same regardless of which day's registry we end up using - self.registry_cache_path = self.cache_dir / "registry" / "hatch_packages_registry.json" - + self.registry_cache_path = ( + self.cache_dir / "registry" / "hatch_packages_registry.json" + ) + # In-memory cache self._registry_cache = None self._last_fetch_time = 0 - + # Set up persistent timestamp file path self._last_fetch_time_path = self.cache_dir / "registry" / ".last_fetch_time" - + # Load persistent timestamp on initialization self._load_last_fetch_time() - + def _load_last_fetch_time(self) -> None: """Load the last fetch timestamp from persistent storage. - + Reads the timestamp from the .last_fetch_time file and sets self._last_fetch_time accordingly. If the file is missing or corrupt, treats the cache as outdated. """ try: if self._last_fetch_time_path.exists(): - with open(self._last_fetch_time_path, 'r', encoding='utf-8') as f: + with open(self._last_fetch_time_path, "r", encoding="utf-8") as f: timestamp_str = f.read().strip() # Parse ISO8601 timestamp - timestamp_dt = datetime.datetime.fromisoformat(timestamp_str.replace('Z', '+00:00')) + timestamp_dt = datetime.datetime.fromisoformat( + timestamp_str.replace("Z", "+00:00") + ) self._last_fetch_time = timestamp_dt.timestamp() - self.logger.debug(f"Loaded last fetch time from disk: {timestamp_str}") + self.logger.debug( + f"Loaded last fetch time from disk: {timestamp_str}" + ) else: - self.logger.debug("No persistent timestamp file found, treating cache as outdated") + self.logger.debug( + "No persistent timestamp file found, treating cache as outdated" + ) except Exception as e: - self.logger.warning(f"Failed to read persistent timestamp: {e}, treating cache as outdated") + self.logger.warning( + f"Failed to read persistent timestamp: {e}, treating cache as outdated" + ) self._last_fetch_time = 0 - + def _save_last_fetch_time(self) -> None: """Save the current fetch timestamp to persistent storage. - + Writes the current UTC timestamp to the .last_fetch_time file in ISO8601 format for persistence across CLI invocations. """ try: # Ensure directory exists self._last_fetch_time_path.parent.mkdir(parents=True, exist_ok=True) - + # Write current UTC time in ISO8601 format current_time = datetime.datetime.now(datetime.timezone.utc) - timestamp_str = current_time.isoformat().replace('+00:00', 'Z') - - with open(self._last_fetch_time_path, 'w', encoding='utf-8') as f: + timestamp_str = current_time.isoformat().replace("+00:00", "Z") + + with open(self._last_fetch_time_path, "w", encoding="utf-8") as f: f.write(timestamp_str) - + self.logger.debug(f"Saved last fetch time to disk: {timestamp_str}") except Exception as e: self.logger.warning(f"Failed to save persistent timestamp: {e}") - + def _read_local_cache(self) -> Dict[str, Any]: """Read the registry from local cache file. - + Returns: Dict[str, Any]: Registry data from cache. - + Raises: Exception: If reading the cache file fails. """ try: - with open(self.registry_cache_path, 'r') as f: + with open(self.registry_cache_path, "r") as f: return json.load(f) except Exception as e: self.logger.error(f"Failed to read local registry file: {e}") raise e - + def _write_local_cache(self, registry_data: Dict[str, Any]) -> None: """Write the registry data to local cache file. - + Args: registry_data (Dict[str, Any]): Registry data to cache. """ try: - with open(self.registry_cache_path, 'w') as f: + with open(self.registry_cache_path, "w") as f: json.dump(registry_data, f, indent=2) except Exception as e: self.logger.error(f"Failed to write local cache: {e}") def _fetch_remote_registry(self) -> Dict[str, Any]: """Fetch registry data from remote URL with fallback to previous day. - + Attempts to fetch today's registry first, falling back to previous day if necessary. Updates the is_delayed flag based on which registry was successfully retrieved. - + Returns: Dict[str, Any]: Registry data from remote source. - + Raises: Exception: If fetching both today's and yesterday's registry fails. """ if self.simulation_mode: try: self.logger.info(f"Fetching registry from {self.registry_url}") - with open(self.registry_cache_path, 'r') as f: + with open(self.registry_cache_path, "r") as f: return json.load(f) except Exception as e: self.logger.error(f"Failed to fetch registry in simulation mode: {e}") raise e - + # Online mode - try today's registry first - date = self.today_date.strftime('%Y-%m-%d') + date = self.today_date.strftime("%Y-%m-%d") if self._registry_exists(date): self.registry_url = f"https://github.com/CrackingShells/Hatch-Registry/releases/download/{date}/hatch_packages_registry.json" self.is_delayed = False # Reset delayed flag for today's registry else: - self.logger.info(f"Today's registry ({date}) not found, falling back to yesterday's") + self.logger.info( + f"Today's registry ({date}) not found, falling back to yesterday's" + ) # Fall back to yesterday's registry yesterday = self.today_date - datetime.timedelta(days=1) - date = yesterday.strftime('%Y-%m-%d') + date = yesterday.strftime("%Y-%m-%d") if not self._registry_exists(date): - self.logger.error(f"Yesterday's registry ({date}) also not found, cannot proceed") + self.logger.error( + f"Yesterday's registry ({date}) also not found, cannot proceed" + ) raise Exception("No valid registry found for today or yesterday") - + # Use yesterday's registry URL self.registry_url = f"https://github.com/CrackingShells/Hatch-Registry/releases/download/{date}/hatch_packages_registry.json" self.is_delayed = True # Set delayed flag for yesterday's registry @@ -195,64 +215,67 @@ def _fetch_remote_registry(self) -> Dict[str, Any]: response = requests.get(self.registry_url, timeout=30) response.raise_for_status() return response.json() - + except Exception as e: self.logger.error(f"Failed to fetch registry from {self.registry_url}: {e}") raise e - + def _registry_exists(self, date_str: str) -> bool: """Check if registry for the given date exists. - + Makes a HEAD request to check if the release page for the given date exists. - + Args: date_str (str): Date string in YYYY-MM-DD format. - + Returns: bool: True if registry exists, False otherwise. """ if self.simulation_mode: return self.registry_cache_path.exists() - - url = f"https://github.com/CrackingShells/Hatch-Registry/releases/tag/{date_str}" + url = ( + f"https://github.com/CrackingShells/Hatch-Registry/releases/tag/{date_str}" + ) try: response = requests.head(url, timeout=10) return response.status_code == 200 except Exception: return False - + def get_registry(self, force_refresh: bool = False) -> Dict[str, Any]: """Fetch the registry file. - + This method implements a multi-level caching strategy: 1. First checks the in-memory cache 2. Then checks the local file cache 3. Finally fetches from the source (local file or remote URL) - + The fetched data is stored in both the in-memory and file caches. - + Args: force_refresh (bool, optional): Force refresh the registry even if cache is valid. Defaults to False. - + Returns: Dict[str, Any]: Registry data. - + Raises: Exception: If fetching the registry fails. """ current_time = datetime.datetime.now(datetime.timezone.utc).timestamp() - + # Check if in-memory cache is valid - if (not force_refresh and - self._registry_cache is not None and - current_time - self._last_fetch_time < self.cache_ttl): + if ( + not force_refresh + and self._registry_cache is not None + and current_time - self._last_fetch_time < self.cache_ttl + ): self.logger.debug("Using in-memory cache") return self._registry_cache - + # Ensure registry cache directory exists self.registry_cache_path.parent.mkdir(parents=True, exist_ok=True) - + # Check if local cache is not outdated if not force_refresh and not self.is_cache_outdated(): try: @@ -261,12 +284,14 @@ def get_registry(self, force_refresh: bool = False) -> Dict[str, Any]: # Update in-memory cache self._registry_cache = registry_data self._last_fetch_time = current_time - + return registry_data except Exception as e: - self.logger.warning(f"Error reading local cache: {e}, will fetch from source instead") + self.logger.warning( + f"Error reading local cache: {e}, will fetch from source instead" + ) # If reading cache fails, continue to fetch from source - + # Fetch from source based on mode try: if self.simulation_mode: @@ -275,32 +300,32 @@ def get_registry(self, force_refresh: bool = False) -> Dict[str, Any]: else: # In online mode, fetch from remote URL registry_data = self._fetch_remote_registry() - + # Update local cache # Note that in case of simulation mode AND default cache path, # we are rewriting the same file with the same content self._write_local_cache(registry_data) - + # Update in-memory cache self._registry_cache = registry_data self._last_fetch_time = current_time - + # Update persistent timestamp self._save_last_fetch_time() - + return registry_data - + except Exception as e: self.logger.error(f"Failed to fetch registry: {e}") raise e - + def is_cache_outdated(self) -> bool: """Check if the cached registry is outdated. - + Determines if the cached registry is outdated based on the persistent timestamp and cache TTL. Falls back to file mtime for backward compatibility if no persistent timestamp is available. - + Returns: bool: True if cache is outdated, False if cache is current. """ @@ -308,13 +333,13 @@ def is_cache_outdated(self) -> bool: return True # If file doesn't exist, consider it outdated now = datetime.datetime.now(datetime.timezone.utc) - + # Use persistent timestamp if available (primary method) if self._last_fetch_time > 0: time_since_fetch = now.timestamp() - self._last_fetch_time if time_since_fetch > self.cache_ttl: return True - + # Also check if cache is not from today (existing logic) last_fetch_dt = datetime.datetime.fromtimestamp( self._last_fetch_time, tz=datetime.timezone.utc @@ -323,13 +348,14 @@ def is_cache_outdated(self) -> bool: return True return False - + return False + # Example usage if __name__ == "__main__": logging.basicConfig(level=logging.INFO) retriever = RegistryRetriever() registry = retriever.get_registry() print(f"Found {len(registry.get('repositories', []))} repositories") - print(f"Registry last updated: {registry.get('last_updated')}") \ No newline at end of file + print(f"Registry last updated: {registry.get('last_updated')}") diff --git a/hatch/template_generator.py b/hatch/template_generator.py index 3557f31..f527218 100644 --- a/hatch/template_generator.py +++ b/hatch/template_generator.py @@ -73,7 +73,7 @@ def generate_hatch_mcp_server_entry_py(package_name: str) -> str: """ -def generate_metadata_json(package_name: str, description: str = ""): +def generate_metadata_json(package_name: str, description: str = "") -> dict: """Generate the metadata JSON content for a template package. Args: diff --git a/mkdocs.yml b/mkdocs.yml index 4893986..1a044b2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,7 +25,7 @@ plugins: show_labels: true show_symbol_type_heading: true show_symbol_type_toc: true - - print-site + - print-site # Must be last to ensure print page has all plugin changes markdown_extensions: - admonition @@ -71,6 +71,7 @@ nav: - Overview: articles/devs/architecture/index.md - System Overview: articles/devs/architecture/system_overview.md - Component Architecture: articles/devs/architecture/component_architecture.md + - CLI Architecture: articles/devs/architecture/cli_architecture.md - MCP Host Configuration: articles/devs/architecture/mcp_host_configuration.md - MCP Host Backup System: articles/devs/architecture/mcp_backup_system.md - Contribution Guides: @@ -83,6 +84,7 @@ nav: - Testing Standards: articles/devs/development_processes/testing_standards.md - Implementation Guides: - Overview: articles/devs/implementation_guides/index.md + - Adding CLI Commands: articles/devs/implementation_guides/adding_cli_commands.md - Adding Installers: articles/devs/implementation_guides/adding_installers.md - Installation Orchestration: articles/devs/implementation_guides/installation_orchestration.md - Package Loader Extensions: articles/devs/implementation_guides/package_loader_extensions.md @@ -91,12 +93,19 @@ nav: - API Reference: - Overview: articles/api/index.md - Core Modules: - - CLI: articles/api/cli.md - Environment Manager: articles/api/environment_manager.md - Package Loader: articles/api/package_loader.md - Python Environment Manager: articles/api/python_environment_manager.md - Registry Explorer: articles/api/registry_explorer.md - Template Generator: articles/api/template_generator.md + - CLI Package: + - Overview: articles/api/cli/index.md + - Entry Point: articles/api/cli/main.md + - Utilities: articles/api/cli/utils.md + - Environment Handlers: articles/api/cli/env.md + - Package Handlers: articles/api/cli/package.md + - MCP Handlers: articles/api/cli/mcp.md + - System Handlers: articles/api/cli/system.md - Installers: - Base Installer: articles/api/installers/base.md - Docker Installer: articles/api/installers/docker.md diff --git a/pyproject.toml b/pyproject.toml index 1a35618..5aa11b4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "hatch-xclam" -version = "0.7.1" +version = "0.8.0-dev.2" description = "Package manager for the Cracking Shells ecosystem" readme = "README.md" requires-python = ">=3.12" @@ -28,10 +28,16 @@ dependencies = [ [project.optional-dependencies] docs = [ "mkdocs>=1.4.0", "mkdocstrings[python]>=0.20.0" ] - dev = [ "wobble>=0.2.0" ] + dev = [ + "cs-wobble>=0.2.0", + "pytest>=8.0.0", + "black>=23.0.0", + "ruff>=0.1.9", + "pre-commit>=3.0.0" +] [project.scripts] - hatch = "hatch.cli_hatch:main" + hatch = "hatch.cli:main" [project.urls] Homepage = "https://github.com/CrackingShells/Hatch" @@ -42,3 +48,24 @@ dependencies = [ [tool.setuptools.packages.find] where = [ "." ] + +[tool.pytest.ini_options] +pythonpath = [ "tests" ] + +[tool.ruff] +exclude = [ + ".git", + ".ruff_cache", + "__pycache__", + "node_modules", + "site", + "py-repo-template", + "cracking-shells-playbook", + "__reports__", + "__design__", + "tests/test_data" +] + + [tool.ruff.lint] + select = [ "E", "F" ] + ignore = [ "E501" ] diff --git a/scripts/fix_unused_test_results.py b/scripts/fix_unused_test_results.py new file mode 100644 index 0000000..b4c80d8 --- /dev/null +++ b/scripts/fix_unused_test_results.py @@ -0,0 +1,235 @@ +#!/usr/bin/env python3 +"""Script to add exit code assertions for unused result variables in tests. + +This script adds assertions for the 42 unused `result` variables in +tests/integration/cli/test_cli_reporter_integration.py identified by ruff F841. + +Strategy: +1. Find lines with "result = handle_*" that are unused +2. Determine expected exit code based on context (dry-run, declined, success) +3. Insert assertion after the result assignment and output capture +""" + +import re +import sys +from pathlib import Path + + +def find_result_assignment_context(lines, line_idx): + """Find context around a result assignment to determine expected exit code. + + Returns: + tuple: (expected_exit_code, reason, insert_line_idx) + """ + # Get context (10 lines before and after) + start = max(0, line_idx - 10) + end = min(len(lines), line_idx + 20) + context_lines = lines[start:end] + context = "\n".join(context_lines) + + print(f"\n{'='*80}") + print(f"Line {line_idx + 1}: {lines[line_idx].strip()}") + print(f"{'='*80}") + + # Find where to insert the assertion + # Look for "output = captured_output.getvalue()" or similar + insert_idx = line_idx + 1 + found_output_line = False + + for i in range(line_idx + 1, end): + line = lines[i].strip() + + # Debug: show what we're looking at + print(f" [{i+1}] {lines[i][:80]}") + + # Found output capture + if "output = " in line and "getvalue()" in line: + found_output_line = True + insert_idx = i + 1 + print(f" -> Found output line at {i+1}, will insert at {insert_idx+1}") + break + + # If we hit another test or class definition, stop + if line.startswith("def test_") or line.startswith("class "): + print(f" -> Hit next test/class at {i+1}, stopping search") + insert_idx = i + break + + if not found_output_line: + print(" -> WARNING: No output line found, inserting after result assignment") + insert_idx = line_idx + 1 + + # Determine expected exit code from context + expected = "EXIT_SUCCESS" + reason = "Operation should succeed" + + # Check for failure scenarios + if "return_value=False" in context: + expected = "EXIT_ERROR" + reason = "User declined confirmation" + print(" -> Detected: User declined (return_value=False)") + elif "dry_run=True" in context or "[DRY RUN]" in context: + expected = "EXIT_SUCCESS" + reason = "Dry-run should succeed" + print(" -> Detected: Dry-run mode") + elif "auto_approve=True" in context: + expected = "EXIT_SUCCESS" + reason = "Auto-approved operation should succeed" + print(" -> Detected: Auto-approve mode") + else: + print(" -> Default: Success case") + + print(f" -> Expected: {expected} - {reason}") + print(f" -> Insert at line: {insert_idx + 1}") + + return expected, reason, insert_idx + + +def get_unused_result_lines(test_file): + """Get current line numbers with unused result variables from ruff.""" + import subprocess + + result = subprocess.run( + ["ruff", "check", str(test_file), "--output-format=concise"], + capture_output=True, + text=True, + ) + + # Parse ruff output for F841 errors with 'result' + result_lines = [] + for line in result.stdout.split("\n"): + if "F841" in line and "result" in line: + # Extract line number from format: "file.py:123:45: F841 ..." + match = re.search(r":(\d+):\d+:", line) + if match: + result_lines.append(int(match.group(1))) + + return sorted(result_lines) + + +def main(): + test_file = Path("tests/integration/cli/test_cli_reporter_integration.py") + + if not test_file.exists(): + print(f"ERROR: {test_file} not found") + sys.exit(1) + + # Get current unused result lines from ruff + print("Running ruff to find unused result variables...") + result_lines = get_unused_result_lines(test_file) + + if not result_lines: + print("βœ“ No unused result variables found!") + sys.exit(0) + + # Read the file + with open(test_file, "r") as f: + content = f.read() + + lines = content.split("\n") + + print(f"Found {len(result_lines)} unused result variables to fix") + print(f"File has {len(lines)} lines") + + # Process in reverse order so line numbers don't shift + modifications = [] + + for line_num in sorted(result_lines, reverse=True): + idx = line_num - 1 # Convert to 0-indexed + + if idx >= len(lines): + print(f"\nWARNING: Line {line_num} is beyond file length ({len(lines)})") + continue + + # Verify this line has "result = " + if "result = " not in lines[idx]: + print(f"\nWARNING: Line {line_num} doesn't contain 'result = '") + print(f" Content: {lines[idx]}") + continue + + # Get context and determine what to insert + expected, reason, insert_idx = find_result_assignment_context(lines, idx) + + # Get indentation from the line before where we're inserting + # This should match the indentation of surrounding code + reference_line = lines[insert_idx - 1] if insert_idx > 0 else lines[idx] + indent = len(reference_line) - len(reference_line.lstrip()) + indent_str = " " * indent + + print(f" -> Reference line for indent: [{insert_idx}] {reference_line[:60]}") + print(f" -> Indent: {indent} spaces") + + # Create assertion lines + assertion_lines = [ + "", + f"{indent_str}# Verify exit code", + f'{indent_str}assert result == {expected}, "{reason}"', + ] + + modifications.append( + { + "line_num": line_num, + "insert_idx": insert_idx, + "lines": assertion_lines, + "expected": expected, + "reason": reason, + } + ) + + # Ask for confirmation + print(f"\n{'='*80}") + print(f"Ready to insert {len(modifications)} assertions") + print(f"{'='*80}") + + response = input("\nProceed with modifications? (yes/no): ") + if response.lower() not in ["yes", "y"]: + print("Aborted") + sys.exit(0) + + # Apply modifications (in reverse order) + for mod in modifications: + insert_idx = mod["insert_idx"] + for line in reversed(mod["lines"]): + lines.insert(insert_idx, line) + print(f"βœ“ Inserted assertion at line {mod['line_num']}: {mod['expected']}") + + # Write back + with open(test_file, "w") as f: + f.write("\n".join(lines)) + + print(f"\nβœ“ Successfully modified {test_file}") + print(f"βœ“ Added {len(modifications)} exit code assertions") + + # Verify with ruff + print("\nRunning ruff to verify...") + import subprocess + + result = subprocess.run( + ["ruff", "check", str(test_file), "--output-format=concise"], + capture_output=True, + text=True, + ) + + # Count remaining F841 errors for result variables + remaining = len( + [ + line + for line in result.stdout.split("\n") + if "F841" in line and "result" in line + ] + ) + + print(f"\nRemaining F841 errors for 'result': {remaining}") + + if remaining == 0: + print("βœ“ All unused result variables fixed!") + else: + print(f"⚠ Still have {remaining} unused result variables") + print("\nRemaining errors:") + for line in result.stdout.split("\n"): + if "F841" in line and "result" in line: + print(f" {line}") + + +if __name__ == "__main__": + main() diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..a5479ce --- /dev/null +++ b/tests/README.md @@ -0,0 +1,134 @@ +# Hatch Test Suite + +## Overview + +The Hatch test suite validates the package manager for the Cracking Shells ecosystem. +Tests are organized into a hierarchical directory structure following the +[CrackingShells Testing Standard](../cracking-shells-playbook/instructions/testing.instructions.md). + +**Quick start:** + +```bash +mamba activate forHatch-dev +python -m pytest tests/ +``` + +## Testing Strategy + +### Mocking Approach + +Tests use `unittest.mock` to isolate units from external dependencies: + +- **Subprocess calls** (`subprocess.run`, `subprocess.Popen`) are mocked to avoid + invoking real system commands (apt-get, pip, conda/mamba, docker). +- **File system operations** are mocked or use `tempfile` for isolation. +- **Network requests** (`requests.get`, `requests.post`) are mocked to avoid + real HTTP calls to package registries. +- **Platform detection** (`sys.platform`, `shutil.which`) is mocked to test + cross-platform behavior on any host OS. + +### Mock Patching Rule + +Always patch where a function is **used**, not where it is **defined**. +See the [testing standard](../cracking-shells-playbook/instructions/testing.instructions.md) +Β§4.4 for detailed guidance. + +### Integration Tests + +Integration tests in `tests/integration/` exercise real component interactions +with mocked external boundaries (file system, network, Docker daemon). +They use `@integration_test(scope=...)` decorators from Wobble. + +## Shared Fixtures + +### `setUpClass` Usage + +Several test modules use `setUpClass` to create expensive shared resources once +per test class, avoiding redundant setup across individual tests: + +| Module | Shared Resource | +|---|---| +| `test_python_installer.py` | Shared virtual environment for pip integration tests | +| `test_python_environment_manager.py` | Shared conda/mamba environment for manager integration tests | +| `test_hatch_installer.py` | Validates `Hatching-Dev` sibling directory exists | + +### Test Data Utilities + +`tests/test_data_utils.py` provides centralized data loading: + +- **`TestDataLoader`** β€” loads configs, responses, and packages from `tests/test_data/`. +- **`NonTTYTestDataLoader`** β€” provides test scenarios for non-TTY environment testing. + +### Static Test Packages + +`tests/test_data/packages/` contains static Hatch packages organized by category: + +- `basic/` β€” simple packages without dependencies +- `dependencies/` β€” packages with various dependency types (system, python, docker, mixed) +- `error_scenarios/` β€” packages that trigger error conditions (circular deps, invalid deps) +- `schema_versions/` β€” packages using different schema versions + +## Test Categories + +Tests follow the three-tier categorization from the CrackingShells Testing Standard: + +### Regression Tests (`tests/regression/`) + +Permanent tests that prevent breaking changes to existing functionality. +Decorated with `@regression_test`. + +- `regression/cli/` β€” CLI output formatting, color logic, table formatting +- `regression/mcp/` β€” MCP field filtering, validation bug guards + +### Integration Tests (`tests/integration/`) + +Tests that validate component interactions and end-to-end workflows. +Decorated with `@integration_test(scope=...)`. + +- `integration/cli/` β€” CLI reporter integration, MCP sync workflows +- `integration/mcp/` β€” Adapter serialization, cross-host sync, host configuration + +### Unit Tests (`tests/unit/`) + +Tests that validate individual components in isolation. + +- `unit/mcp/` β€” Adapter protocol, adapter registry, config model validation + +### Root-Level Tests (`tests/test_*.py`) + +Legacy tests not yet migrated to the hierarchical structure. +These cover core functionality: installers, environment management, +package loading, registry, and non-TTY integration. + +## Running Tests + +```bash +# Run all tests +python -m pytest tests/ + +# Run by category +python -m pytest tests/regression/ +python -m pytest tests/integration/ +python -m pytest tests/unit/ + +# Run with timing info +python -m pytest tests/ --durations=30 + +# Run a specific test file +python -m pytest tests/test_env_manip.py -v +``` + +## Resolved Issues + +All previously known test issues have been fixed: + +| Issue | Resolution | +|---|---| +| `test_cli_version.py` collection error | Fixed: obsolete `handle_mcp_show` import removed from `cli_hatch.py` | +| `test_color_enum_total_count` assertion | Fixed: expected count updated to 15 (AMBER color added) | +| `test_get_environment_activation_info_windows` on macOS | Fixed: test skipped on non-Windows platforms | +| `test_handler_shows_prompt_before_confirmation` assertion | Fixed: updated for new exit code behavior | +| `test_mcp_show_invalid_subcommand_error` assertion | Fixed: updated for new error message format | +| `test_hatch_installer.py` setup errors | Fixed: tests skip when `Hatching-Dev` directory is missing | + +**Current status**: 683 passed, 26 skipped, 0 failures, 0 errors (100% pass rate). diff --git a/tests/cli_test_utils.py b/tests/cli_test_utils.py new file mode 100644 index 0000000..5a09a33 --- /dev/null +++ b/tests/cli_test_utils.py @@ -0,0 +1,280 @@ +"""Test utilities for CLI handler testing. + +This module provides helper functions to simplify test setup for CLI handlers, +particularly for creating Namespace objects and mock managers. + +These utilities reduce boilerplate in test files and ensure consistent +test patterns across the CLI test suite. + +IMPORTANT: The attribute names in create_mcp_configure_args MUST match +the exact names expected by handle_mcp_configure in hatch/cli/cli_mcp.py. +""" + +import sys +from argparse import Namespace +from pathlib import Path +from typing import Any, Dict, List, Optional +from unittest.mock import MagicMock + +# Add the parent directory to the path to import hatch modules +sys.path.insert(0, str(Path(__file__).parent.parent)) + + +def create_mcp_configure_args( + host: str = "claude-desktop", + server_name: str = "test-server", + server_command: Optional[str] = "python", + args: Optional[List[str]] = None, + env_var: Optional[List[str]] = None, + url: Optional[str] = None, + header: Optional[List[str]] = None, + timeout: Optional[int] = None, + trust: bool = False, + cwd: Optional[str] = None, + env_file: Optional[str] = None, + http_url: Optional[str] = None, + include_tools: Optional[List[str]] = None, + exclude_tools: Optional[List[str]] = None, + input: Optional[List[str]] = None, + disabled: Optional[bool] = None, + auto_approve_tools: Optional[List[str]] = None, + disable_tools: Optional[List[str]] = None, + env_vars: Optional[List[str]] = None, + startup_timeout: Optional[int] = None, + tool_timeout: Optional[int] = None, + enabled: Optional[bool] = None, + bearer_token_env_var: Optional[str] = None, + env_header: Optional[List[str]] = None, + no_backup: bool = False, + dry_run: bool = False, + auto_approve: bool = False, + _use_default_args: bool = True, +) -> Namespace: + """Create a Namespace object for handle_mcp_configure testing. + + This helper creates a properly structured Namespace object that matches + the expected arguments for handle_mcp_configure, making tests more + readable and maintainable. + + IMPORTANT: Attribute names MUST match those in handle_mcp_configure: + - server_command (not command) + - env_var (not env) + - input (not inputs) + + Args: + host: Target MCP host (e.g., 'claude-desktop', 'cursor', 'vscode') + server_name: Name of the MCP server to configure + server_command: Command to run for local servers + args: Arguments for the command (defaults to ['server.py'] for local servers) + env_var: Environment variables in KEY=VALUE format + url: URL for SSE remote servers + header: HTTP headers in KEY=VALUE format + timeout: Server timeout in seconds + trust: Trust the server (Cursor) + cwd: Working directory + env_file: Environment file path + http_url: URL for HTTP remote servers (Gemini only) + include_tools: Tools to include (Gemini) + exclude_tools: Tools to exclude (Gemini) + input: VSCode input configurations + disabled: Whether the server should be disabled + auto_approve_tools: Tools to auto-approve (Kiro) + disable_tools: Tools to disable (Kiro) + env_vars: Additional environment variables + startup_timeout: Startup timeout + tool_timeout: Tool execution timeout + enabled: Whether server is enabled + bearer_token_env_var: Bearer token environment variable + env_header: Environment headers + no_backup: Disable backup creation + dry_run: Preview changes without applying + auto_approve: Skip confirmation prompts + _use_default_args: If True and args is None and server_command is set, use default args + + Returns: + Namespace object with all arguments set + """ + # Only use default args for local servers (when command is set) + if args is None and server_command is not None and _use_default_args: + args = ["server.py"] + + return Namespace( + host=host, + server_name=server_name, + server_command=server_command, + args=args, + env_var=env_var, + url=url, + header=header, + timeout=timeout, + trust=trust, + cwd=cwd, + env_file=env_file, + http_url=http_url, + include_tools=include_tools, + exclude_tools=exclude_tools, + input=input, + disabled=disabled, + auto_approve_tools=auto_approve_tools, + disable_tools=disable_tools, + env_vars=env_vars, + startup_timeout=startup_timeout, + tool_timeout=tool_timeout, + enabled=enabled, + bearer_token_env_var=bearer_token_env_var, + env_header=env_header, + no_backup=no_backup, + dry_run=dry_run, + auto_approve=auto_approve, + ) + + +def create_mcp_remove_args( + host: str = "claude-desktop", + server_name: str = "test-server", + no_backup: bool = False, + dry_run: bool = False, + auto_approve: bool = False, +) -> Namespace: + """Create a Namespace object for handle_mcp_remove testing. + + Args: + host: Target MCP host + server_name: Name of the MCP server to remove + no_backup: Disable backup creation + dry_run: Preview changes without applying + auto_approve: Skip confirmation prompts + + Returns: + Namespace object with all arguments set + """ + return Namespace( + host=host, + server_name=server_name, + no_backup=no_backup, + dry_run=dry_run, + auto_approve=auto_approve, + ) + + +def create_mcp_remove_server_args( + env_manager: Any = None, + server_name: str = "test-server", + host: Optional[str] = None, + env: Optional[str] = None, + no_backup: bool = False, + dry_run: bool = False, + auto_approve: bool = False, +) -> Namespace: + """Create a Namespace object for handle_mcp_remove_server testing. + + Args: + env_manager: Environment manager instance + server_name: Name of the MCP server to remove + host: Comma-separated list of target hosts + env: Environment name + no_backup: Disable backup creation + dry_run: Preview changes without applying + auto_approve: Skip confirmation prompts + + Returns: + Namespace object with all arguments set + """ + return Namespace( + env_manager=env_manager, + server_name=server_name, + host=host, + env=env, + no_backup=no_backup, + dry_run=dry_run, + auto_approve=auto_approve, + ) + + +def create_mcp_remove_host_args( + env_manager: Any = None, + host_name: str = "claude-desktop", + no_backup: bool = False, + dry_run: bool = False, + auto_approve: bool = False, +) -> Namespace: + """Create a Namespace object for handle_mcp_remove_host testing. + + Args: + env_manager: Environment manager instance + host_name: Name of the host to remove configuration from + no_backup: Disable backup creation + dry_run: Preview changes without applying + auto_approve: Skip confirmation prompts + + Returns: + Namespace object with all arguments set + """ + return Namespace( + env_manager=env_manager, + host_name=host_name, + no_backup=no_backup, + dry_run=dry_run, + auto_approve=auto_approve, + ) + + +def create_mock_env_manager( + current_env: str = "default", + environments: Optional[List[str]] = None, + packages: Optional[Dict[str, Any]] = None, +) -> MagicMock: + """Create a mock HatchEnvironmentManager for testing. + + Args: + current_env: Name of the current environment + environments: List of available environment names + packages: Dictionary of packages in the environment + + Returns: + MagicMock configured as a HatchEnvironmentManager + """ + if environments is None: + environments = ["default"] + if packages is None: + packages = {} + + mock_manager = MagicMock() + mock_manager.get_current_environment.return_value = current_env + mock_manager.list_environments.return_value = environments + mock_manager.get_environment_packages.return_value = packages + mock_manager.environment_exists.side_effect = lambda name: name in environments + + return mock_manager + + +def create_mock_mcp_manager( + hosts: Optional[List[str]] = None, + servers: Optional[Dict[str, Dict[str, Any]]] = None, +) -> MagicMock: + """Create a mock MCPHostConfigurationManager for testing. + + Args: + hosts: List of available host names + servers: Dictionary mapping host names to their server configurations + + Returns: + MagicMock configured as an MCPHostConfigurationManager + """ + if hosts is None: + hosts = ["claude-desktop", "cursor", "vscode"] + if servers is None: + servers = {} + + mock_manager = MagicMock() + mock_manager.list_hosts.return_value = hosts + mock_manager.get_servers.side_effect = lambda host: servers.get(host, {}) + + # Configure successful operations by default + mock_result = MagicMock() + mock_result.success = True + mock_result.backup_path = None + mock_manager.configure_server.return_value = mock_result + mock_manager.remove_server.return_value = mock_result + + return mock_manager diff --git a/tests/integration/__init__.py b/tests/integration/__init__.py index b256412..e82d614 100644 --- a/tests/integration/__init__.py +++ b/tests/integration/__init__.py @@ -2,4 +2,4 @@ Integration tests for Hatch MCP functionality. These tests validate component interactions and end-to-end workflows. -""" \ No newline at end of file +""" diff --git a/tests/integration/cli/__init__.py b/tests/integration/cli/__init__.py new file mode 100644 index 0000000..37b2b20 --- /dev/null +++ b/tests/integration/cli/__init__.py @@ -0,0 +1,14 @@ +"""Integration tests for CLI reporter infrastructure. + +This package contains integration tests for CLI handler β†’ ResultReporter flow: +- Handler creates ResultReporter with correct command name +- Handler adds consequences before confirmation prompt +- Dry-run flag propagates correctly +- ConversionReport integration in MCP handlers + +These tests verify component communication and data flow integrity +across the CLI reporting system. + +Test Groups: + test_cli_reporter_integration.py: Handler β†’ ResultReporter integration +""" diff --git a/tests/integration/cli/test_cli_reporter_integration.py b/tests/integration/cli/test_cli_reporter_integration.py new file mode 100644 index 0000000..a0490f5 --- /dev/null +++ b/tests/integration/cli/test_cli_reporter_integration.py @@ -0,0 +1,2946 @@ +"""Integration tests for CLI handler β†’ ResultReporter flow. + +These tests verify that CLI handlers correctly integrate with ResultReporter +for unified output rendering. Focus is on component communication, not output format. + +Reference: R05 Β§3.7 (05-test_definition_v0.md) β€” CLI Handler Integration test group + +Test Strategy: +- Tests verify that handlers USE ResultReporter (import and instantiate) +- Tests fail if handlers don't import ResultReporter from cli_utils +- Once handlers are updated, tests will pass +""" + +import pytest +from argparse import Namespace +from unittest.mock import MagicMock, patch +import io + +from hatch.cli.cli_utils import EXIT_SUCCESS + + +def _handler_uses_result_reporter(handler_module_source: str) -> bool: + """Check if handler module imports and uses ResultReporter. + + This is a simple source code check to verify the handler has been updated. + """ + return "ResultReporter" in handler_module_source + + +class TestMCPConfigureHandlerIntegration: + """Integration tests for handle_mcp_configure β†’ ResultReporter flow.""" + + def test_handler_imports_result_reporter(self): + """Handler module should import ResultReporter from cli_utils. + + This test verifies that the handler has been updated to use the new + ResultReporter infrastructure instead of display_report. + + Risk: R3 (ConversionReport mapping loses field data) + """ + import inspect + from hatch.cli import cli_mcp + + # Get the source code of the module + source = inspect.getsource(cli_mcp) + + # Verify ResultReporter is imported + assert ( + "from hatch.cli.cli_utils import" in source and "ResultReporter" in source + ), "handle_mcp_configure should import ResultReporter from cli_utils" + + def test_handler_uses_result_reporter_for_output(self): + """Handler should use ResultReporter instead of display_report. + + Verifies that handle_mcp_configure creates a ResultReporter and uses + add_from_conversion_report() for ConversionReport integration. + + Risk: R3 (ConversionReport mapping loses field data) + """ + from hatch.cli.cli_mcp import handle_mcp_configure + + # Create mock args for a simple configure operation + args = Namespace( + host="claude-desktop", + server_name="test-server", + server_command="python", + args=["server.py"], + env_var=None, + url=None, + header=None, + timeout=None, + trust=False, + cwd=None, + env_file=None, + http_url=None, + include_tools=None, + exclude_tools=None, + input=None, + disabled=None, + auto_approve_tools=None, + disable_tools=None, + env_vars=None, + startup_timeout=None, + tool_timeout=None, + enabled=None, + bearer_token_env_var=None, + env_header=None, + no_backup=True, + dry_run=False, + auto_approve=True, # Skip confirmation + ) + + # Mock the MCPHostConfigurationManager + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_manager.get_server_config.return_value = None # New server + mock_result = MagicMock() + mock_result.success = True + mock_result.backup_path = None + mock_manager.configure_server.return_value = mock_result + mock_manager_class.return_value = mock_manager + + # Capture stdout to verify ResultReporter output format + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + # Run the handler + result = handle_mcp_configure(args) + + output = captured_output.getvalue() + + # Verify output uses new format (ResultReporter style) + # The new format should have [SUCCESS] and [CONFIGURED] patterns + assert ( + "[SUCCESS]" in output or result == 0 + ), "Handler should produce success output" + + def test_handler_dry_run_shows_preview(self): + """Dry-run flag should show preview without executing. + + Risk: R5 (Dry-run mode not propagated correctly) + """ + from hatch.cli.cli_mcp import handle_mcp_configure + + args = Namespace( + host="claude-desktop", + server_name="test-server", + server_command="python", + args=["server.py"], + env_var=None, + url=None, + header=None, + timeout=None, + trust=False, + cwd=None, + env_file=None, + http_url=None, + include_tools=None, + exclude_tools=None, + input=None, + disabled=None, + auto_approve_tools=None, + disable_tools=None, + env_vars=None, + startup_timeout=None, + tool_timeout=None, + enabled=None, + bearer_token_env_var=None, + env_header=None, + no_backup=True, + dry_run=True, # Dry-run enabled + auto_approve=True, + ) + + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_manager.get_server_config.return_value = None + mock_manager_class.return_value = mock_manager + + # Capture stdout + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_configure(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Dry-run should succeed" + + # Verify dry-run output format + assert ( + "[DRY RUN]" in output + ), "Dry-run should show [DRY RUN] prefix in output" + + # Verify configure_server was NOT called (dry-run doesn't execute) + mock_manager.configure_server.assert_not_called() + + def test_handler_shows_prompt_before_confirmation(self): + """Handler should show consequence preview before requesting confirmation. + + Risk: R1 (Consequence data lost/corrupted during tracking) + """ + from hatch.cli.cli_mcp import handle_mcp_configure + + args = Namespace( + host="claude-desktop", + server_name="test-server", + server_command="python", + args=["server.py"], + env_var=None, + url=None, + header=None, + timeout=None, + trust=False, + cwd=None, + env_file=None, + http_url=None, + include_tools=None, + exclude_tools=None, + input=None, + disabled=None, + auto_approve_tools=None, + disable_tools=None, + env_vars=None, + startup_timeout=None, + tool_timeout=None, + enabled=None, + bearer_token_env_var=None, + env_header=None, + no_backup=True, + dry_run=False, + auto_approve=False, # Will prompt for confirmation + ) + + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_manager.get_server_config.return_value = None + mock_manager_class.return_value = mock_manager + + # Capture stdout and mock confirmation to decline + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + with patch( + "hatch.cli.cli_utils.request_confirmation", return_value=False + ): + result = handle_mcp_configure(args) + + output = captured_output.getvalue() + + # Verify exit code - CLI now returns success (0) when user declines + assert result == 0, "User declined confirmation should return success" + + # Verify prompt was shown (should contain command name and CONFIGURE verb) + assert ( + "hatch mcp configure" in output or "[CONFIGURE]" in output + ), "Handler should show consequence preview before confirmation" + + +class TestMCPSyncHandlerIntegration: + """Integration tests for handle_mcp_sync β†’ ResultReporter flow.""" + + def test_sync_handler_imports_result_reporter(self): + """Sync handler module should import ResultReporter. + + Risk: R1 (Consequence data lost/corrupted) + """ + import inspect + from hatch.cli import cli_mcp + + source = inspect.getsource(cli_mcp) + + # Verify ResultReporter is imported and used in sync handler + assert "ResultReporter" in source, "cli_mcp module should import ResultReporter" + + def test_sync_handler_uses_result_reporter(self): + """Sync handler should use ResultReporter for output. + + Risk: R1 (Consequence data lost/corrupted) + """ + from hatch.cli.cli_mcp import handle_mcp_sync + + args = Namespace( + from_env=None, + from_host="claude-desktop", + to_host="cursor", + servers=None, + dry_run=False, + auto_approve=True, + no_backup=True, + ) + + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_result = MagicMock() + mock_result.success = True + mock_result.servers_synced = 1 + mock_result.hosts_updated = 1 + mock_result.results = [] + mock_manager.sync_configurations.return_value = mock_result + mock_manager_class.return_value = mock_manager + + # Capture stdout + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_sync(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify output uses ResultReporter format + # ResultReporter uses [SYNC] for prompt and [SYNCED] for result, or [SUCCESS] header + assert ( + "[SUCCESS]" in output or "[SYNCED]" in output or "[SYNC]" in output + ), f"Sync handler should use ResultReporter output format. Got: {output}" + + +class TestMCPRemoveHandlerIntegration: + """Integration tests for handle_mcp_remove β†’ ResultReporter flow.""" + + def test_remove_handler_uses_result_reporter(self): + """Remove handler should use ResultReporter for output. + + Risk: R1 (Consequence data lost/corrupted) + """ + from hatch.cli.cli_mcp import handle_mcp_remove + + args = Namespace( + host="claude-desktop", + server_name="test-server", + no_backup=True, + dry_run=False, + auto_approve=True, + ) + + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_result = MagicMock() + mock_result.success = True + mock_result.backup_path = None + mock_manager.remove_server.return_value = mock_result + mock_manager_class.return_value = mock_manager + + # Capture stdout + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_remove(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify output uses ResultReporter format + assert ( + "[SUCCESS]" in output or "[REMOVED]" in output + ), "Remove handler should use ResultReporter output format" + + +class TestMCPBackupHandlerIntegration: + """Integration tests for MCP backup handlers β†’ ResultReporter flow.""" + + def test_backup_restore_handler_uses_result_reporter(self): + """Backup restore handler should use ResultReporter for output. + + Risk: R1 (Consequence data lost/corrupted) + """ + from hatch.cli.cli_mcp import handle_mcp_backup_restore + from hatch.mcp_host_config.backup import MCPHostConfigBackupManager + from pathlib import Path + import tempfile + + # Create mock env_manager + mock_env_manager = MagicMock() + mock_env_manager.apply_restored_host_configuration_to_environments.return_value = ( + 0 + ) + + args = Namespace( + env_manager=mock_env_manager, + host="claude-desktop", + backup_file=None, + dry_run=False, + auto_approve=True, + ) + + # Create a temporary backup file for the test + with tempfile.TemporaryDirectory() as tmpdir: + backup_dir = Path(tmpdir) / "claude-desktop" + backup_dir.mkdir(parents=True) + backup_file = backup_dir / "mcp.json.claude-desktop.20260130_120000_000000" + backup_file.write_text('{"mcpServers": {}}') + + # Mock the backup manager to use our temp directory + # Store original for potential restoration (currently unused) + # original_init = MCPHostConfigBackupManager.__init__ + + def mock_init(self, backup_root=None): + self.backup_root = Path(tmpdir) + self.backup_root.mkdir(parents=True, exist_ok=True) + from hatch.mcp_host_config.backup import AtomicFileOperations + + self.atomic_ops = AtomicFileOperations() + + with patch.object(MCPHostConfigBackupManager, "__init__", mock_init): + with patch.object( + MCPHostConfigBackupManager, "restore_backup", return_value=True + ): + # Mock the strategy for post-restore sync + with patch("hatch.mcp_host_config.strategies"): + with patch( + "hatch.cli.cli_mcp.MCPHostRegistry" + ) as mock_registry: + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = MagicMock( + servers={} + ) + mock_registry.get_strategy.return_value = mock_strategy + + # Capture stdout + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_backup_restore(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify output uses ResultReporter format + assert ( + "[SUCCESS]" in output or "[RESTORED]" in output + ), f"Backup restore handler should use ResultReporter output format. Got: {output}" + + def test_backup_clean_handler_uses_result_reporter(self): + """Backup clean handler should use ResultReporter for output. + + Risk: R1 (Consequence data lost/corrupted) + """ + from hatch.cli.cli_mcp import handle_mcp_backup_clean + from hatch.mcp_host_config.backup import MCPHostConfigBackupManager + + args = Namespace( + host="claude-desktop", + older_than_days=30, + keep_count=None, + dry_run=False, + auto_approve=True, + ) + + with patch.object(MCPHostConfigBackupManager, "__init__", return_value=None): + with patch.object(MCPHostConfigBackupManager, "list_backups") as mock_list: + mock_backup_info = MagicMock() + mock_backup_info.age_days = 45 + mock_backup_info.file_path = MagicMock() + mock_backup_info.file_path.name = "old_backup.json" + mock_list.return_value = [mock_backup_info] + + with patch.object( + MCPHostConfigBackupManager, "clean_backups", return_value=1 + ): + # Capture stdout + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_backup_clean(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify output uses ResultReporter format + assert ( + "[SUCCESS]" in output + or "[CLEANED]" in output + or "cleaned" in output.lower() + ), "Backup clean handler should use ResultReporter output format" + + +class TestMCPListServersHostCentric: + """Integration tests for host-centric mcp list servers command. + + Reference: R02 Β§2.5 (02-list_output_format_specification_v2.md) + Reference: R09 Β§1 (09-implementation_gap_analysis_v0.md) - Critical deviation analysis + + These tests verify that handle_mcp_list_servers: + 1. Reads from actual host config files (not environment data) + 2. Shows ALL servers (Hatch-managed βœ… and 3rd party ❌) + 3. Cross-references with environments for Hatch status + 4. Supports --host flag to filter to specific host + 5. Supports --pattern flag for regex filtering + """ + + def test_list_servers_reads_from_host_config(self): + """Command should read servers from host config files, not environment data. + + This is the CRITICAL test for host-centric design. + The command must read from actual host config files (e.g., ~/.claude/config.json) + and show ALL servers, not just Hatch-managed packages. + + Risk: Architectural deviation - package-centric vs host-centric + """ + from hatch.cli.cli_mcp import handle_mcp_list_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + # Create mock env_manager with dict-based return values (matching real implementation) + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "weather-server", + "version": "1.0.0", + "configured_hosts": { + "claude-desktop": {"configured_at": "2026-01-30"} + }, + } + ] + } + + args = Namespace( + env_manager=mock_env_manager, + host="claude-desktop", + json=False, + ) + + # Mock the host strategy to return servers from config file + # This simulates reading from ~/.claude/config.json + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="python", args=["weather.py"] + ), + "custom-tool": MCPServerConfig( + name="custom-tool", command="node", args=["custom.js"] + ), # 3rd party! + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + + # Import strategies to trigger registration + with patch("hatch.mcp_host_config.strategies"): + # Capture stdout + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # CRITICAL: Verify the command reads from host config (strategy.read_configuration called) + mock_strategy.read_configuration.assert_called_once() + + # Verify BOTH servers appear in output (Hatch-managed AND 3rd party) + assert ( + "weather-server" in output + ), "Hatch-managed server should appear in output" + assert ( + "custom-tool" in output + ), "3rd party server should appear in output (host-centric design)" + + # Verify Hatch status indicators + assert "βœ…" in output, "Hatch-managed server should show βœ…" + assert "❌" in output, "3rd party server should show ❌" + + def test_list_servers_shows_third_party_servers(self): + """Command should show 3rd party servers with ❌ status. + + A 3rd party server is one configured directly on the host + that is NOT tracked in any Hatch environment. + + Risk: Missing 3rd party servers in output + """ + from hatch.cli.cli_mcp import handle_mcp_list_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + # Create mock env_manager with NO packages (empty environment) + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host=None, # No filter - show all hosts + json=False, + ) + + # Host config has a server that's NOT in any Hatch environment + mock_host_config = HostConfiguration( + servers={ + "external-tool": MCPServerConfig( + name="external-tool", command="external", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # 3rd party server should appear with ❌ status + assert ( + "external-tool" in output + ), "3rd party server should appear in output" + assert ( + "❌" in output + ), "3rd party server should show ❌ (not Hatch-managed)" + + def test_list_servers_without_host_shows_all_hosts(self): + """Without --host flag, command should show servers from ALL available hosts. + + Reference: R02 Β§2.5 - "Without --host: shows all servers across all hosts" + """ + from hatch.cli.cli_mcp import handle_mcp_list_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host=None, # No host filter - show ALL hosts + json=False, + ) + + # Create configs for multiple hosts + claude_config = HostConfiguration( + servers={ + "server-a": MCPServerConfig(name="server-a", command="python", args=[]), + } + ) + cursor_config = HostConfiguration( + servers={ + "server-b": MCPServerConfig(name="server-b", command="node", args=[]), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + # Mock detect_available_hosts to return multiple hosts + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP, + MCPHostType.CURSOR, + ] + + # Mock get_strategy to return different configs per host + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Both servers from different hosts should appear + assert "server-a" in output, "Server from claude-desktop should appear" + assert "server-b" in output, "Server from cursor should appear" + + # Host column should be present (since no --host filter) + assert ( + "claude-desktop" in output or "Host" in output + ), "Host column should be present when showing all hosts" + + def test_list_servers_host_filter_pattern(self): + """--host flag should filter by host name using regex pattern. + + Reference: R10 Β§3.2 - "--host accepts regex patterns" + """ + from hatch.cli.cli_mcp import handle_mcp_list_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host="claude.*", # Regex pattern + json=False, + ) + + claude_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="python", args=[] + ), + } + ) + cursor_config = HostConfiguration( + servers={ + "fetch-server": MCPServerConfig( + name="fetch-server", command="node", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP, + MCPHostType.CURSOR, + ] + + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Server from claude-desktop should appear (matches pattern) + assert ( + "weather-server" in output + ), "weather-server should appear (host matches pattern)" + + # Server from cursor should NOT appear (doesn't match pattern) + assert ( + "fetch-server" not in output + ), "fetch-server should NOT appear (cursor doesn't match 'claude.*')" + + def test_list_servers_json_output_host_centric(self): + """JSON output should include host-centric data structure. + + Reference: R10 Β§3.2 - JSON output format for mcp list servers + """ + from hatch.cli.cli_mcp import handle_mcp_list_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + import json + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "managed-server", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + } + + args = Namespace( + env_manager=mock_env_manager, + host=None, # No filter - show all hosts + json=True, # JSON output + ) + + mock_host_config = HostConfiguration( + servers={ + "managed-server": MCPServerConfig( + name="managed-server", command="python", args=[] + ), + "unmanaged-server": MCPServerConfig( + name="unmanaged-server", command="node", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Parse JSON output + data = json.loads(output) + + # Verify structure per R10 Β§8 + assert "rows" in data, "JSON should include rows array" + + # Verify both servers present with correct fields + server_names = [s["server"] for s in data["rows"]] + assert "managed-server" in server_names + assert "unmanaged-server" in server_names + + # Verify hatch_managed status and host field + for row in data["rows"]: + assert "host" in row, "Each row should have host field" + assert ( + "hatch_managed" in row + ), "Each row should have hatch_managed field" + if row["server"] == "managed-server": + assert row["hatch_managed"] + assert row["environment"] == "default" + elif row["server"] == "unmanaged-server": + assert not row["hatch_managed"] + + +class TestMCPListHostsHostCentric: + """Integration tests for host-centric mcp list hosts command. + + Reference: R10 Β§3.1 (10-namespace_consistency_specification_v2.md) + + These tests verify that handle_mcp_list_hosts: + 1. Reads from actual host config files (not environment data) + 2. Shows host/server pairs with columns: Host β†’ Server β†’ Hatch β†’ Environment + 3. Supports --server flag to filter by server name regex + 4. First column (Host) sorted alphabetically + """ + + def test_mcp_list_hosts_uniform_output(self): + """Command should produce uniform table output with Host β†’ Server β†’ Hatch β†’ Environment columns. + + Reference: R10 Β§3.1 - Column order matches command structure + """ + from hatch.cli.cli_mcp import handle_mcp_list_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "weather-server", + "version": "1.0.0", + "configured_hosts": { + "claude-desktop": {"configured_at": "2026-01-30"} + }, + } + ] + } + + args = Namespace( + env_manager=mock_env_manager, + server=None, # No filter + json=False, + ) + + # Host config has both Hatch-managed and 3rd party servers + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="python", args=["weather.py"] + ), + "custom-tool": MCPServerConfig( + name="custom-tool", command="node", args=["custom.js"] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify column headers present + assert "Host" in output, "Host column should be present" + assert "Server" in output, "Server column should be present" + assert "Hatch" in output, "Hatch column should be present" + assert "Environment" in output, "Environment column should be present" + + # Verify both servers appear + assert "weather-server" in output, "Hatch-managed server should appear" + assert "custom-tool" in output, "3rd party server should appear" + + # Verify Hatch status indicators + assert "βœ…" in output, "Hatch-managed server should show βœ…" + assert "❌" in output, "3rd party server should show ❌" + + def test_mcp_list_hosts_server_filter_exact(self): + """--server flag with exact name should filter to matching servers only. + + Reference: R10 Β§3.1 - --server filter + """ + from hatch.cli.cli_mcp import handle_mcp_list_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server="weather-server", # Exact match filter + json=False, + ) + + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="python", args=[] + ), + "fetch-server": MCPServerConfig( + name="fetch-server", command="node", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching server should appear + assert "weather-server" in output, "weather-server should match filter" + + # Non-matching server should NOT appear + assert "fetch-server" not in output, "fetch-server should NOT appear" + + def test_mcp_list_hosts_server_filter_pattern(self): + """--server flag with regex pattern should filter matching servers. + + Reference: R10 Β§3.1 - --server accepts regex patterns + """ + from hatch.cli.cli_mcp import handle_mcp_list_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server=".*-server", # Regex pattern + json=False, + ) + + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="python", args=[] + ), + "fetch-server": MCPServerConfig( + name="fetch-server", command="node", args=[] + ), + "custom-tool": MCPServerConfig( + name="custom-tool", command="node", args=[] + ), # Should NOT match + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching servers should appear + assert "weather-server" in output, "weather-server should match pattern" + assert "fetch-server" in output, "fetch-server should match pattern" + + # Non-matching server should NOT appear + assert ( + "custom-tool" not in output + ), "custom-tool should NOT match pattern" + + def test_mcp_list_hosts_alphabetical_ordering(self): + """First column (Host) should be sorted alphabetically. + + Reference: R10 Β§1.3 - Alphabetical ordering + """ + from hatch.cli.cli_mcp import handle_mcp_list_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server=None, + json=False, + ) + + # Create configs for multiple hosts + claude_config = HostConfiguration( + servers={ + "server-a": MCPServerConfig(name="server-a", command="python", args=[]), + } + ) + cursor_config = HostConfiguration( + servers={ + "server-b": MCPServerConfig(name="server-b", command="node", args=[]), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + # Return hosts in non-alphabetical order to test sorting + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CURSOR, # Should come second alphabetically + MCPHostType.CLAUDE_DESKTOP, # Should come first alphabetically + ] + + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Find positions of hosts in output + claude_pos = output.find("claude-desktop") + cursor_pos = output.find("cursor") + + # claude-desktop should appear before cursor (alphabetically) + assert ( + claude_pos < cursor_pos + ), "Hosts should be sorted alphabetically (claude-desktop before cursor)" + + +class TestEnvListHostsCommand: + """Integration tests for env list hosts command. + + Reference: R10 Β§3.3 (10-namespace_consistency_specification_v2.md) + + These tests verify that handle_env_list_hosts: + 1. Reads from environment data (Hatch-managed packages only) + 2. Shows environment/host/server deployments with columns: Environment β†’ Host β†’ Server β†’ Version + 3. Supports --env and --server filters (regex patterns) + 4. First column (Environment) sorted alphabetically + """ + + def test_env_list_hosts_uniform_output(self): + """Command should produce uniform table output with Environment β†’ Host β†’ Server β†’ Version columns. + + Reference: R10 Β§3.3 - Column order matches command structure + """ + from hatch.cli.cli_env import handle_env_list_hosts + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [ + {"name": "default", "is_current": True}, + {"name": "dev", "is_current": False}, + ] + mock_env_manager.get_environment_data.side_effect = lambda env_name: { + "default": { + "packages": [ + { + "name": "weather-server", + "version": "1.0.0", + "configured_hosts": { + "claude-desktop": {"configured_at": "2026-01-30"}, + "cursor": {"configured_at": "2026-01-30"}, + }, + } + ] + }, + "dev": { + "packages": [ + { + "name": "test-server", + "version": "0.1.0", + "configured_hosts": { + "claude-desktop": {"configured_at": "2026-01-30"}, + }, + } + ] + }, + }.get(env_name, {"packages": []}) + + args = Namespace( + env_manager=mock_env_manager, + env=None, + server=None, + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify column headers present + assert "Environment" in output, "Environment column should be present" + assert "Host" in output, "Host column should be present" + assert "Server" in output, "Server column should be present" + assert "Version" in output, "Version column should be present" + + # Verify data appears + assert "default" in output, "default environment should appear" + assert "dev" in output, "dev environment should appear" + assert "weather-server" in output, "weather-server should appear" + assert "test-server" in output, "test-server should appear" + + def test_env_list_hosts_env_filter_exact(self): + """--env flag with exact name should filter to matching environment only. + + Reference: R10 Β§3.3 - --env filter + """ + from hatch.cli.cli_env import handle_env_list_hosts + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [ + {"name": "default"}, + {"name": "dev"}, + ] + mock_env_manager.get_environment_data.side_effect = lambda env_name: { + "default": { + "packages": [ + { + "name": "server-a", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + "dev": { + "packages": [ + { + "name": "server-b", + "version": "0.1.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + }.get(env_name, {"packages": []}) + + args = Namespace( + env_manager=mock_env_manager, + env="default", # Exact match filter + server=None, + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching environment should appear + assert "server-a" in output, "server-a from default should appear" + + # Non-matching environment should NOT appear + assert "server-b" not in output, "server-b from dev should NOT appear" + + def test_env_list_hosts_env_filter_pattern(self): + """--env flag with regex pattern should filter matching environments. + + Reference: R10 Β§3.3 - --env accepts regex patterns + """ + from hatch.cli.cli_env import handle_env_list_hosts + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [ + {"name": "default"}, + {"name": "dev"}, + {"name": "dev-staging"}, + ] + mock_env_manager.get_environment_data.side_effect = lambda env_name: { + "default": { + "packages": [ + { + "name": "server-a", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + "dev": { + "packages": [ + { + "name": "server-b", + "version": "0.1.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + "dev-staging": { + "packages": [ + { + "name": "server-c", + "version": "0.2.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + }.get(env_name, {"packages": []}) + + args = Namespace( + env_manager=mock_env_manager, + env="dev.*", # Regex pattern + server=None, + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching environments should appear + assert "server-b" in output, "server-b from dev should appear" + assert "server-c" in output, "server-c from dev-staging should appear" + + # Non-matching environment should NOT appear + assert "server-a" not in output, "server-a from default should NOT appear" + + def test_env_list_hosts_server_filter(self): + """--server flag should filter by server name regex. + + Reference: R10 Β§3.3 - --server filter + """ + from hatch.cli.cli_env import handle_env_list_hosts + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "weather-server", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + { + "name": "fetch-server", + "version": "2.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + { + "name": "custom-tool", + "version": "0.5.0", + "configured_hosts": {"claude-desktop": {}}, + }, + ] + } + + args = Namespace( + env_manager=mock_env_manager, + env=None, + server=".*-server", # Regex pattern + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching servers should appear + assert "weather-server" in output, "weather-server should match pattern" + assert "fetch-server" in output, "fetch-server should match pattern" + + # Non-matching server should NOT appear + assert "custom-tool" not in output, "custom-tool should NOT match pattern" + + def test_env_list_hosts_combined_filters(self): + """Combined --env and --server filters should work with AND logic. + + Reference: R10 Β§1.5 - Combined filters + """ + from hatch.cli.cli_env import handle_env_list_hosts + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [ + {"name": "default"}, + {"name": "dev"}, + ] + mock_env_manager.get_environment_data.side_effect = lambda env_name: { + "default": { + "packages": [ + { + "name": "weather-server", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + { + "name": "fetch-server", + "version": "2.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + ] + }, + "dev": { + "packages": [ + { + "name": "weather-server", + "version": "0.9.0", + "configured_hosts": {"claude-desktop": {}}, + }, + ] + }, + }.get(env_name, {"packages": []}) + + args = Namespace( + env_manager=mock_env_manager, + env="default", + server="weather.*", + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Only weather-server from default should appear + assert "weather-server" in output, "weather-server from default should appear" + assert "1.0.0" in output, "Version 1.0.0 should appear" + + # fetch-server should NOT appear (doesn't match server filter) + assert "fetch-server" not in output, "fetch-server should NOT appear" + + # dev environment should NOT appear (doesn't match env filter) + assert "0.9.0" not in output, "Version 0.9.0 from dev should NOT appear" + + +class TestEnvListServersCommand: + """Integration tests for env list servers command. + + Reference: R10 Β§3.4 (10-namespace_consistency_specification_v2.md) + + These tests verify that handle_env_list_servers: + 1. Reads from environment data (Hatch-managed packages only) + 2. Shows environment/server/host deployments with columns: Environment β†’ Server β†’ Host β†’ Version + 3. Shows '-' for undeployed packages + 4. Supports --env and --host filters (regex patterns) + 5. Supports --host - to show only undeployed packages + 6. First column (Environment) sorted alphabetically + """ + + def test_env_list_servers_uniform_output(self): + """Command should produce uniform table output with Environment β†’ Server β†’ Host β†’ Version columns. + + Reference: R10 Β§3.4 - Column order matches command structure + """ + from hatch.cli.cli_env import handle_env_list_servers + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [ + {"name": "default"}, + {"name": "dev"}, + ] + mock_env_manager.get_environment_data.side_effect = lambda env_name: { + "default": { + "packages": [ + { + "name": "weather-server", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + { + "name": "util-lib", + "version": "0.5.0", + "configured_hosts": {}, # Undeployed + }, + ] + }, + "dev": { + "packages": [ + { + "name": "test-server", + "version": "0.1.0", + "configured_hosts": {"cursor": {}}, + } + ] + }, + }.get(env_name, {"packages": []}) + + args = Namespace( + env_manager=mock_env_manager, + env=None, + host=None, + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify column headers present + assert "Environment" in output, "Environment column should be present" + assert "Server" in output, "Server column should be present" + assert "Host" in output, "Host column should be present" + assert "Version" in output, "Version column should be present" + + # Verify data appears + assert "default" in output, "default environment should appear" + assert "dev" in output, "dev environment should appear" + assert "weather-server" in output, "weather-server should appear" + assert "util-lib" in output, "util-lib should appear" + assert "test-server" in output, "test-server should appear" + + def test_env_list_servers_env_filter_exact(self): + """--env flag with exact name should filter to matching environment only. + + Reference: R10 Β§3.4 - --env filter + """ + from hatch.cli.cli_env import handle_env_list_servers + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [ + {"name": "default"}, + {"name": "dev"}, + ] + mock_env_manager.get_environment_data.side_effect = lambda env_name: { + "default": { + "packages": [ + { + "name": "server-a", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + "dev": { + "packages": [ + { + "name": "server-b", + "version": "0.1.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + }.get(env_name, {"packages": []}) + + args = Namespace( + env_manager=mock_env_manager, + env="default", + host=None, + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching environment should appear + assert "server-a" in output, "server-a from default should appear" + + # Non-matching environment should NOT appear + assert "server-b" not in output, "server-b from dev should NOT appear" + + def test_env_list_servers_env_filter_pattern(self): + """--env flag with regex pattern should filter matching environments. + + Reference: R10 Β§3.4 - --env accepts regex patterns + """ + from hatch.cli.cli_env import handle_env_list_servers + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [ + {"name": "default"}, + {"name": "dev"}, + {"name": "dev-staging"}, + ] + mock_env_manager.get_environment_data.side_effect = lambda env_name: { + "default": { + "packages": [ + { + "name": "server-a", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + "dev": { + "packages": [ + { + "name": "server-b", + "version": "0.1.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + "dev-staging": { + "packages": [ + { + "name": "server-c", + "version": "0.2.0", + "configured_hosts": {"claude-desktop": {}}, + } + ] + }, + }.get(env_name, {"packages": []}) + + args = Namespace( + env_manager=mock_env_manager, + env="dev.*", + host=None, + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching environments should appear + assert "server-b" in output, "server-b from dev should appear" + assert "server-c" in output, "server-c from dev-staging should appear" + + # Non-matching environment should NOT appear + assert "server-a" not in output, "server-a from default should NOT appear" + + def test_env_list_servers_host_filter_exact(self): + """--host flag with exact name should filter to matching host only. + + Reference: R10 Β§3.4 - --host filter + """ + from hatch.cli.cli_env import handle_env_list_servers + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "server-a", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + { + "name": "server-b", + "version": "2.0.0", + "configured_hosts": {"cursor": {}}, + }, + ] + } + + args = Namespace( + env_manager=mock_env_manager, + env=None, + host="claude-desktop", + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching host should appear + assert "server-a" in output, "server-a on claude-desktop should appear" + + # Non-matching host should NOT appear + assert "server-b" not in output, "server-b on cursor should NOT appear" + + def test_env_list_servers_host_filter_pattern(self): + """--host flag with regex pattern should filter matching hosts. + + Reference: R10 Β§3.4 - --host accepts regex patterns + """ + from hatch.cli.cli_env import handle_env_list_servers + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "server-a", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + { + "name": "server-b", + "version": "2.0.0", + "configured_hosts": {"cursor": {}}, + }, + { + "name": "server-c", + "version": "3.0.0", + "configured_hosts": {"claude-code": {}}, + }, + ] + } + + args = Namespace( + env_manager=mock_env_manager, + env=None, + host="claude.*", # Regex pattern + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Matching hosts should appear + assert "server-a" in output, "server-a on claude-desktop should appear" + assert "server-c" in output, "server-c on claude-code should appear" + + # Non-matching host should NOT appear + assert "server-b" not in output, "server-b on cursor should NOT appear" + + def test_env_list_servers_host_filter_undeployed(self): + """--host - should show only undeployed packages. + + Reference: R10 Β§3.4 - Special filter for undeployed packages + """ + from hatch.cli.cli_env import handle_env_list_servers + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "deployed-server", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + { + "name": "util-lib", + "version": "0.5.0", + "configured_hosts": {}, + }, # Undeployed + { + "name": "debug-lib", + "version": "0.3.0", + "configured_hosts": {}, + }, # Undeployed + ] + } + + args = Namespace( + env_manager=mock_env_manager, + env=None, + host="-", # Special filter for undeployed + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Undeployed packages should appear + assert "util-lib" in output, "util-lib (undeployed) should appear" + assert "debug-lib" in output, "debug-lib (undeployed) should appear" + + # Deployed package should NOT appear + assert "deployed-server" not in output, "deployed-server should NOT appear" + + def test_env_list_servers_combined_filters(self): + """Combined --env and --host filters should work with AND logic. + + Reference: R10 Β§1.5 - Combined filters + """ + from hatch.cli.cli_env import handle_env_list_servers + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [ + {"name": "default"}, + {"name": "dev"}, + ] + mock_env_manager.get_environment_data.side_effect = lambda env_name: { + "default": { + "packages": [ + { + "name": "server-a", + "version": "1.0.0", + "configured_hosts": {"claude-desktop": {}}, + }, + { + "name": "server-b", + "version": "2.0.0", + "configured_hosts": {"cursor": {}}, + }, + ] + }, + "dev": { + "packages": [ + { + "name": "server-c", + "version": "0.1.0", + "configured_hosts": {"claude-desktop": {}}, + }, + ] + }, + }.get(env_name, {"packages": []}) + + args = Namespace( + env_manager=mock_env_manager, + env="default", + host="claude-desktop", + json=False, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_env_list_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Only server-a from default on claude-desktop should appear + assert "server-a" in output, "server-a should appear" + + # server-b should NOT appear (wrong host) + assert "server-b" not in output, "server-b should NOT appear" + + # server-c should NOT appear (wrong env) + assert "server-c" not in output, "server-c should NOT appear" + + +class TestMCPShowHostsCommand: + """Integration tests for hatch mcp show hosts command. + + Reference: R11 Β§2.1 (11-enhancing_show_command_v0.md) - Show hosts specification + + These tests verify that handle_mcp_show_hosts: + 1. Shows detailed host configurations with hierarchical output + 2. Supports --server filter for regex pattern matching + 3. Omits hosts with no matching servers when filter applied + 4. Shows horizontal separators between host sections + 5. Highlights entity names with amber + bold + 6. Supports --json output format + """ + + def test_mcp_show_hosts_no_filter(self): + """Command should show all hosts with detailed configuration. + + Reference: R11 Β§2.1 - Output format without filter + """ + from hatch.cli.cli_mcp import handle_mcp_show_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "weather-server", + "version": "1.0.0", + "configured_hosts": { + "claude-desktop": {"configured_at": "2026-01-30"} + }, + } + ] + } + + args = Namespace( + env_manager=mock_env_manager, + server=None, # No filter + json=False, + ) + + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=["weather-mcp"] + ), + "custom-tool": MCPServerConfig( + name="custom-tool", command="node", args=["custom.js"] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should show host header + assert "claude-desktop" in output, "Host name should appear" + + # Should show both servers + assert "weather-server" in output, "weather-server should appear" + assert "custom-tool" in output, "custom-tool should appear" + + # Should show server details + assert ( + "Command:" in output or "uvx" in output + ), "Server command should appear" + + def test_mcp_show_hosts_server_filter_exact(self): + """--server filter should match exact server name. + + Reference: R11 Β§2.1 - Server filter with exact match + """ + from hatch.cli.cli_mcp import handle_mcp_show_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server="weather-server", # Exact match + json=False, + ) + + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=["weather-mcp"] + ), + "fetch-server": MCPServerConfig( + name="fetch-server", command="python", args=["fetch.py"] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should show matching server + assert "weather-server" in output, "weather-server should appear" + + # Should NOT show non-matching server + assert "fetch-server" not in output, "fetch-server should NOT appear" + + def test_mcp_show_hosts_server_filter_pattern(self): + """--server filter should support regex patterns. + + Reference: R11 Β§2.1 - Server filter with regex pattern + """ + from hatch.cli.cli_mcp import handle_mcp_show_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server=".*-server", # Regex pattern + json=False, + ) + + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=[] + ), + "fetch-server": MCPServerConfig( + name="fetch-server", command="python", args=[] + ), + "custom-tool": MCPServerConfig( + name="custom-tool", command="node", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should show matching servers + assert "weather-server" in output, "weather-server should appear" + assert "fetch-server" in output, "fetch-server should appear" + + # Should NOT show non-matching server + assert "custom-tool" not in output, "custom-tool should NOT appear" + + def test_mcp_show_hosts_omits_empty_hosts(self): + """Hosts with no matching servers should be omitted. + + Reference: R11 Β§2.1 - Empty host omission + """ + from hatch.cli.cli_mcp import handle_mcp_show_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server="weather-server", # Only matches on claude-desktop + json=False, + ) + + claude_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=[] + ), + } + ) + cursor_config = HostConfiguration( + servers={ + "fetch-server": MCPServerConfig( + name="fetch-server", command="python", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP, + MCPHostType.CURSOR, + ] + + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # claude-desktop should appear (has matching server) + assert "claude-desktop" in output, "claude-desktop should appear" + + # cursor should NOT appear (no matching servers) + assert ( + "cursor" not in output + ), "cursor should NOT appear (no matching servers)" + + def test_mcp_show_hosts_alphabetical_ordering(self): + """Hosts should be sorted alphabetically. + + Reference: R11 Β§1.4 - Alphabetical ordering + """ + from hatch.cli.cli_mcp import handle_mcp_show_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server=None, + json=False, + ) + + mock_config = HostConfiguration( + servers={ + "server-a": MCPServerConfig(name="server-a", command="python", args=[]), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + # Return hosts in non-alphabetical order + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CURSOR, + MCPHostType.CLAUDE_DESKTOP, + ] + + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Find positions of host names + claude_pos = output.find("claude-desktop") + cursor_pos = output.find("cursor") + + # claude-desktop should appear before cursor (alphabetically) + assert ( + claude_pos < cursor_pos + ), "Hosts should be sorted alphabetically (claude-desktop before cursor)" + + def test_mcp_show_hosts_horizontal_separators(self): + """Output should have horizontal separators between host sections. + + Reference: R11 Β§3.1 - Horizontal separators + """ + from hatch.cli.cli_mcp import handle_mcp_show_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server=None, + json=False, + ) + + mock_config = HostConfiguration( + servers={ + "server-a": MCPServerConfig(name="server-a", command="python", args=[]), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should have horizontal separator (═ character) + assert "═" in output, "Output should have horizontal separators" + + def test_mcp_show_hosts_json_output(self): + """--json flag should output JSON format. + + Reference: R11 Β§6.1 - JSON output format + """ + from hatch.cli.cli_mcp import handle_mcp_show_hosts + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + import json + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + server=None, + json=True, # JSON output + ) + + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=["weather-mcp"] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_hosts(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should be valid JSON + try: + data = json.loads(output) + except json.JSONDecodeError: + pytest.fail(f"Output should be valid JSON: {output}") + + # Should have hosts array + assert "hosts" in data, "JSON should have 'hosts' key" + assert len(data["hosts"]) > 0, "Should have at least one host" + + # Host should have expected structure + host = data["hosts"][0] + assert "host" in host, "Host should have 'host' key" + assert "servers" in host, "Host should have 'servers' key" + + +class TestMCPShowServersCommand: + """Integration tests for hatch mcp show servers command. + + Reference: R11 Β§2.2 (11-enhancing_show_command_v0.md) - Show servers specification + + These tests verify that handle_mcp_show_servers: + 1. Shows detailed server configurations across hosts + 2. Supports --host filter for regex pattern matching + 3. Omits servers with no matching hosts when filter applied + 4. Shows horizontal separators between server sections + 5. Highlights entity names with amber + bold + 6. Supports --json output format + """ + + def test_mcp_show_servers_no_filter(self): + """Command should show all servers with host configurations. + + Reference: R11 Β§2.2 - Output format without filter + """ + from hatch.cli.cli_mcp import handle_mcp_show_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = { + "packages": [ + { + "name": "weather-server", + "version": "1.0.0", + "configured_hosts": { + "claude-desktop": {"configured_at": "2026-01-30"} + }, + } + ] + } + + args = Namespace( + env_manager=mock_env_manager, + host=None, # No filter + json=False, + ) + + claude_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=["weather-mcp"] + ), + "fetch-server": MCPServerConfig( + name="fetch-server", command="python", args=["fetch.py"] + ), + } + ) + cursor_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=["weather-mcp"] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP, + MCPHostType.CURSOR, + ] + + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should show both servers + assert "weather-server" in output, "weather-server should appear" + assert "fetch-server" in output, "fetch-server should appear" + + # Should show host configurations + assert "claude-desktop" in output, "claude-desktop should appear" + assert "cursor" in output, "cursor should appear" + + def test_mcp_show_servers_host_filter_exact(self): + """--host filter should match exact host name. + + Reference: R11 Β§2.2 - Host filter with exact match + """ + from hatch.cli.cli_mcp import handle_mcp_show_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host="claude-desktop", # Exact match + json=False, + ) + + claude_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=[] + ), + } + ) + cursor_config = HostConfiguration( + servers={ + "fetch-server": MCPServerConfig( + name="fetch-server", command="python", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP, + MCPHostType.CURSOR, + ] + + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should show server from matching host + assert "weather-server" in output, "weather-server should appear" + + # Should NOT show server only on non-matching host + assert "fetch-server" not in output, "fetch-server should NOT appear" + + def test_mcp_show_servers_host_filter_pattern(self): + """--host filter should support regex patterns. + + Reference: R11 Β§2.2 - Host filter with regex pattern + """ + from hatch.cli.cli_mcp import handle_mcp_show_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host="claude.*", # Regex pattern + json=False, + ) + + claude_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=[] + ), + } + ) + cursor_config = HostConfiguration( + servers={ + "fetch-server": MCPServerConfig( + name="fetch-server", command="python", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP, + MCPHostType.CURSOR, + ] + + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should show server from matching host + assert "weather-server" in output, "weather-server should appear" + + # Should NOT show server only on non-matching host + assert "fetch-server" not in output, "fetch-server should NOT appear" + + def test_mcp_show_servers_host_filter_multi_pattern(self): + """--host filter should support multi-pattern regex. + + Reference: R11 Β§2.2 - Host filter with multi-pattern + """ + from hatch.cli.cli_mcp import handle_mcp_show_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host="claude-desktop|cursor", # Multi-pattern + json=False, + ) + + claude_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=[] + ), + } + ) + cursor_config = HostConfiguration( + servers={ + "fetch-server": MCPServerConfig( + name="fetch-server", command="python", args=[] + ), + } + ) + kiro_config = HostConfiguration( + servers={ + "debug-server": MCPServerConfig( + name="debug-server", command="node", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP, + MCPHostType.CURSOR, + MCPHostType.KIRO, + ] + + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + elif host_type == MCPHostType.KIRO: + mock_strategy.read_configuration.return_value = kiro_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should show servers from matching hosts + assert "weather-server" in output, "weather-server should appear" + assert "fetch-server" in output, "fetch-server should appear" + + # Should NOT show server only on non-matching host + assert "debug-server" not in output, "debug-server should NOT appear" + + def test_mcp_show_servers_omits_empty_servers(self): + """Servers with no matching hosts should be omitted. + + Reference: R11 Β§2.2 - Empty server omission + """ + from hatch.cli.cli_mcp import handle_mcp_show_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host="claude-desktop", # Only matches claude-desktop + json=False, + ) + + claude_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=[] + ), + } + ) + cursor_config = HostConfiguration( + servers={ + "fetch-server": MCPServerConfig( + name="fetch-server", command="python", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP, + MCPHostType.CURSOR, + ] + + def get_strategy_side_effect(host_type): + mock_strategy = MagicMock() + mock_strategy.get_config_path.return_value = MagicMock( + exists=lambda: True + ) + if host_type == MCPHostType.CLAUDE_DESKTOP: + mock_strategy.read_configuration.return_value = claude_config + elif host_type == MCPHostType.CURSOR: + mock_strategy.read_configuration.return_value = cursor_config + else: + mock_strategy.read_configuration.return_value = HostConfiguration( + servers={} + ) + return mock_strategy + + mock_registry.get_strategy.side_effect = get_strategy_side_effect + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # weather-server should appear (has matching host) + assert "weather-server" in output, "weather-server should appear" + + # fetch-server should NOT appear (no matching hosts) + assert "fetch-server" not in output, "fetch-server should NOT appear" + + def test_mcp_show_servers_alphabetical_ordering(self): + """Servers should be sorted alphabetically. + + Reference: R11 Β§1.4 - Alphabetical ordering + """ + from hatch.cli.cli_mcp import handle_mcp_show_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host=None, + json=False, + ) + + # Servers in non-alphabetical order + mock_config = HostConfiguration( + servers={ + "zebra-server": MCPServerConfig( + name="zebra-server", command="python", args=[] + ), + "alpha-server": MCPServerConfig( + name="alpha-server", command="python", args=[] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Find positions of server names + alpha_pos = output.find("alpha-server") + zebra_pos = output.find("zebra-server") + + # alpha-server should appear before zebra-server (alphabetically) + assert ( + alpha_pos < zebra_pos + ), "Servers should be sorted alphabetically (alpha-server before zebra-server)" + + def test_mcp_show_servers_horizontal_separators(self): + """Output should have horizontal separators between server sections. + + Reference: R11 Β§3.1 - Horizontal separators + """ + from hatch.cli.cli_mcp import handle_mcp_show_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host=None, + json=False, + ) + + mock_config = HostConfiguration( + servers={ + "server-a": MCPServerConfig(name="server-a", command="python", args=[]), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should have horizontal separator (═ character) + assert "═" in output, "Output should have horizontal separators" + + def test_mcp_show_servers_json_output(self): + """--json flag should output JSON format. + + Reference: R11 Β§6.2 - JSON output format + """ + from hatch.cli.cli_mcp import handle_mcp_show_servers + from hatch.mcp_host_config import MCPHostType, MCPServerConfig + from hatch.mcp_host_config.models import HostConfiguration + import json + + mock_env_manager = MagicMock() + mock_env_manager.list_environments.return_value = [{"name": "default"}] + mock_env_manager.get_environment_data.return_value = {"packages": []} + + args = Namespace( + env_manager=mock_env_manager, + host=None, + json=True, # JSON output + ) + + mock_host_config = HostConfiguration( + servers={ + "weather-server": MCPServerConfig( + name="weather-server", command="uvx", args=["weather-mcp"] + ), + } + ) + + with patch("hatch.cli.cli_mcp.MCPHostRegistry") as mock_registry: + mock_registry.detect_available_hosts.return_value = [ + MCPHostType.CLAUDE_DESKTOP + ] + mock_strategy = MagicMock() + mock_strategy.read_configuration.return_value = mock_host_config + mock_strategy.get_config_path.return_value = MagicMock(exists=lambda: True) + mock_registry.get_strategy.return_value = mock_strategy + + with patch("hatch.mcp_host_config.strategies"): + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_show_servers(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Should be valid JSON + try: + data = json.loads(output) + except json.JSONDecodeError: + pytest.fail(f"Output should be valid JSON: {output}") + + # Should have servers array + assert "servers" in data, "JSON should have 'servers' key" + assert len(data["servers"]) > 0, "Should have at least one server" + + # Server should have expected structure + server = data["servers"][0] + assert "name" in server, "Server should have 'name' key" + assert "hosts" in server, "Server should have 'hosts' key" + + +class TestMCPShowCommandRemoval: + """Tests for mcp show command behavior after removal of legacy syntax. + + Reference: R11 Β§5 (11-enhancing_show_command_v0.md) - Migration Path + + These tests verify that: + 1. 'hatch mcp show' without subcommand shows help/error + 2. Invalid subcommands show appropriate error + """ + + def test_mcp_show_without_subcommand_shows_help(self): + """'hatch mcp show' without subcommand should show help message. + + Reference: R11 Β§5.3 - Clean removal + """ + from hatch.cli.__main__ import _route_mcp_command + + # Create args with no show_command + args = Namespace( + mcp_command="show", + show_command=None, + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = _route_mcp_command(args) + + output = captured_output.getvalue() + + # Should return error code + assert result == 1, "Should return error code when no subcommand" + + # Should show helpful message + assert ( + "hosts" in output or "servers" in output + ), "Error message should mention available subcommands" + + def test_mcp_show_invalid_subcommand_error(self): + """Invalid subcommand should show error message. + + Reference: R11 Β§5.3 - Clean removal + """ + from hatch.cli.__main__ import _route_mcp_command + + # Create args with invalid show_command + args = Namespace( + mcp_command="show", + show_command="invalid", + ) + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = _route_mcp_command(args) + + output = captured_output.getvalue() + + # Should return error code + assert result == 1, "Should return error code for invalid subcommand" + # Verify error message in output - message now says "Unknown" instead of "error" or "invalid" + assert ( + "error" in output.lower() + or "invalid" in output.lower() + or "unknown" in output.lower() + ), "Should show error message" diff --git a/tests/integration/cli/test_mcp_sync_detailed.py b/tests/integration/cli/test_mcp_sync_detailed.py new file mode 100644 index 0000000..d75fd2a --- /dev/null +++ b/tests/integration/cli/test_mcp_sync_detailed.py @@ -0,0 +1,362 @@ +"""Integration tests for hatch mcp sync --detailed flag. + +These tests verify the --detailed flag functionality using canonical fixture data +from tests/test_data/mcp_adapters/canonical_configs.json. This ensures tests use +realistic MCP server configurations that match the actual host specifications. + +Test Coverage: + - Detailed output with all consequence types + - Standard output without detailed flag + - Host-specific field differences (e.g., VSCode β†’ Cursor) + - Filtering by consequence type (e.g., --detailed updated) + +Architecture: + - Uses HostRegistry to load canonical configs for each host + - Mocks MCPHostConfigurationManager to control sync behavior + - Verifies ResultReporter output includes field-level details + - Tests both generate_reports=True and generate_reports=False paths +""" + +import io +from argparse import Namespace +from pathlib import Path +from unittest.mock import MagicMock, patch + + +from hatch.cli.cli_mcp import handle_mcp_sync +from hatch.cli.cli_utils import EXIT_SUCCESS +from hatch.mcp_host_config.models import ( + ConfigurationResult, + SyncResult, + MCPHostType, +) +from hatch.mcp_host_config.reporting import ConversionReport, FieldOperation +from tests.test_data.mcp_adapters.host_registry import HostRegistry + +# Load canonical configs fixture +# This provides realistic MCP server configurations for all supported hosts +FIXTURES_PATH = ( + Path(__file__).resolve().parents[2] + / "test_data" + / "mcp_adapters" + / "canonical_configs.json" +) +REGISTRY = HostRegistry(FIXTURES_PATH) + + +class TestMCPSyncDetailed: + """Tests for --detailed flag in hatch mcp sync command.""" + + def test_sync_with_detailed_all(self): + """Test sync with --detailed all shows field-level details. + + Uses canonical fixture data from claude-desktop and cursor configs. + """ + # Load canonical configs from fixtures + claude_host = REGISTRY.get_host("claude-desktop") + claude_config = claude_host.load_config() + + args = Namespace( + from_host="claude-desktop", + from_env=None, + to_host="cursor", + servers=None, + pattern=None, + dry_run=False, + auto_approve=True, + no_backup=True, + detailed="all", + ) + + # Create conversion report using fixture data + # Cursor supports envFile, Claude Desktop doesn't - this creates an UPDATED field + report = ConversionReport( + operation="create", + server_name="mcp-server", + target_host=MCPHostType.CURSOR, + field_operations=[ + FieldOperation( + field_name="command", + operation="UPDATED", + old_value=None, + new_value=claude_config.command, + ), + FieldOperation( + field_name="args", + operation="UPDATED", + old_value=None, + new_value=claude_config.args, + ), + FieldOperation( + field_name="env", + operation="UPDATED", + old_value=None, + new_value=claude_config.env, + ), + FieldOperation( + field_name="type", + operation="UPDATED", + old_value=None, + new_value=claude_config.type, + ), + ], + ) + + # Create mock result with conversion reports + mock_result = SyncResult( + success=True, + servers_synced=1, + hosts_updated=1, + results=[ + ConfigurationResult( + success=True, + hostname="cursor", + conversion_reports=[report], + ) + ], + ) + + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_manager.preview_sync.return_value = ["test-server"] + mock_manager.sync_configurations.return_value = mock_result + mock_manager_class.return_value = mock_manager + + # Capture stdout + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_sync(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify detailed output includes field-level changes from fixture data + assert "command" in output, "Should show command field" + assert "python" in output, "Should show command value from fixture" + assert ( + "args" in output or "-m" in output + ), "Should show args field from fixture" + assert ( + "env" in output or "API_KEY" in output + ), "Should show env field from fixture" + assert ( + "[CONFIGURED]" in output or "[CONFIGURE]" in output + ), "Should show CONFIGURE consequence" + + # Verify sync_configurations was called with generate_reports=True + mock_manager.sync_configurations.assert_called_once() + call_kwargs = mock_manager.sync_configurations.call_args[1] + assert ( + call_kwargs["generate_reports"] is True + ), "Should request detailed reports" + + def test_sync_without_detailed_no_field_details(self): + """Test sync without --detailed shows only high-level results.""" + args = Namespace( + from_host="claude-desktop", + from_env=None, + to_host="cursor", + servers=None, + pattern=None, + dry_run=False, + auto_approve=True, + no_backup=True, + detailed=None, # No detailed flag + ) + + mock_result = SyncResult( + success=True, + servers_synced=1, + hosts_updated=1, + results=[ + ConfigurationResult( + success=True, + hostname="cursor", + conversion_reports=[], # No reports + ) + ], + ) + + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_manager.preview_sync.return_value = ["test-server"] + mock_manager.sync_configurations.return_value = mock_result + mock_manager_class.return_value = mock_manager + + # Capture stdout + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_sync(args) + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify sync_configurations was called with generate_reports=False + mock_manager.sync_configurations.assert_called_once() + call_kwargs = mock_manager.sync_configurations.call_args[1] + assert ( + call_kwargs["generate_reports"] is False + ), "Should not request detailed reports" + + def test_sync_detailed_with_host_specific_fields(self): + """Test detailed output shows host-specific field differences. + + Syncing from VSCode (has envFile + inputs) to Cursor (has envFile, no inputs) + should show inputs as UNSUPPORTED. + """ + # Load canonical configs + vscode_host = REGISTRY.get_host("vscode") + vscode_config = vscode_host.load_config() + + args = Namespace( + from_host="vscode", + from_env=None, + to_host="cursor", + servers=None, + pattern=None, + dry_run=False, + auto_approve=True, + no_backup=True, + detailed="all", + ) + + # Create report showing VSCode-specific fields + report = ConversionReport( + operation="create", + server_name="vscode-server", + target_host=MCPHostType.CURSOR, + field_operations=[ + FieldOperation( + field_name="command", + operation="UPDATED", + old_value=None, + new_value=vscode_config.command, + ), + FieldOperation( + field_name="envFile", + operation="UPDATED", + old_value=None, + new_value=vscode_config.envFile, + ), + FieldOperation( + field_name="inputs", + operation="UNSUPPORTED", + new_value=vscode_config.inputs, + ), + ], + ) + + mock_result = SyncResult( + success=True, + servers_synced=1, + hosts_updated=1, + results=[ + ConfigurationResult( + success=True, + hostname="cursor", + conversion_reports=[report], + ) + ], + ) + + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_manager.preview_sync.return_value = ["vscode-server"] + mock_manager.sync_configurations.return_value = mock_result + mock_manager_class.return_value = mock_manager + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_sync(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # Verify output shows host-specific field handling + assert "envFile" in output, "Should show envFile (supported by both)" + assert "inputs" in output, "Should show inputs field" + assert ( + "[SKIPPED]" in output or "unsupported" in output.lower() + ), "Should mark inputs as unsupported/skipped" + + def test_sync_detailed_filter_by_consequence_type(self): + """Test filtering detailed output by consequence type.""" + claude_host = REGISTRY.get_host("claude-desktop") + claude_config = claude_host.load_config() + + args = Namespace( + from_host="claude-desktop", + from_env=None, + to_host="cursor", + servers=None, + pattern=None, + dry_run=False, + auto_approve=True, + no_backup=True, + detailed="updated", # Filter to only UPDATED consequences + ) + + # Create report with mixed operations + report = ConversionReport( + operation="update", + server_name="test-server", + target_host=MCPHostType.CURSOR, + field_operations=[ + FieldOperation( + field_name="command", + operation="UPDATED", + old_value="python", + new_value="uvx", + ), + FieldOperation( + field_name="args", + operation="UNCHANGED", + new_value=claude_config.args, + ), + ], + ) + + mock_result = SyncResult( + success=True, + servers_synced=1, + hosts_updated=1, + results=[ + ConfigurationResult( + success=True, + hostname="cursor", + conversion_reports=[report], + ) + ], + ) + + with patch( + "hatch.cli.cli_mcp.MCPHostConfigurationManager" + ) as mock_manager_class: + mock_manager = MagicMock() + mock_manager.preview_sync.return_value = ["test-server"] + mock_manager.sync_configurations.return_value = mock_result + mock_manager_class.return_value = mock_manager + + captured_output = io.StringIO() + with patch("sys.stdout", captured_output): + result = handle_mcp_sync(args) + + output = captured_output.getvalue() + + # Verify exit code + assert result == EXIT_SUCCESS, "Operation should succeed" + + # When filtering by UPDATED, should show UPDATED fields + # The filtering logic is complex - just verify it doesn't crash + # and produces some output + assert len(output) > 0, "Should produce output" diff --git a/tests/integration/mcp/__init__.py b/tests/integration/mcp/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/integration/mcp/test_adapter_serialization.py b/tests/integration/mcp/test_adapter_serialization.py new file mode 100644 index 0000000..4d411c5 --- /dev/null +++ b/tests/integration/mcp/test_adapter_serialization.py @@ -0,0 +1,184 @@ +"""Integration tests for adapter serialization. + +DEPRECATED: This test file is deprecated and will be removed in v0.9.0. +Replaced by: tests/integration/mcp/test_host_configuration.py (per-host) + tests/integration/mcp/test_cross_host_sync.py (cross-host) +Reason: Migrating to data-driven test architecture (see 01-test-definition_v0.md) + +Test IDs: AS-01 to AS-10 (per 02-test_architecture_rebuild_v0.md) +Scope: Full serialization flow for each adapter with realistic configs. +""" + +import unittest + +import pytest + +from hatch.mcp_host_config.models import MCPServerConfig +from hatch.mcp_host_config.adapters import ( + ClaudeAdapter, + CodexAdapter, + GeminiAdapter, + KiroAdapter, + VSCodeAdapter, +) + +DEPRECATION_REASON = "Deprecated - replaced by data-driven tests (test_host_configuration.py, test_cross_host_sync.py)" + + +@pytest.mark.skip(reason=DEPRECATION_REASON) +class TestClaudeAdapterSerialization(unittest.TestCase): + """Integration tests for Claude adapter serialization.""" + + def test_AS01_claude_stdio_serialization(self): + """AS-01: Claude stdio config serializes correctly.""" + config = MCPServerConfig( + name="my-server", + command="python", + args=["-m", "mcp_server"], + env={"API_KEY": "secret"}, + type="stdio", + ) + + adapter = ClaudeAdapter() + result = adapter.serialize(config) + + self.assertEqual(result["command"], "python") + self.assertEqual(result["args"], ["-m", "mcp_server"]) + self.assertEqual(result["env"], {"API_KEY": "secret"}) + self.assertEqual(result["type"], "stdio") + self.assertNotIn("name", result) + + def test_AS02_claude_sse_serialization(self): + """AS-02: Claude SSE config serializes correctly.""" + config = MCPServerConfig( + name="remote-server", + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer token"}, + type="sse", + ) + + adapter = ClaudeAdapter() + result = adapter.serialize(config) + + self.assertEqual(result["url"], "https://api.example.com/mcp") + self.assertEqual(result["headers"], {"Authorization": "Bearer token"}) + self.assertEqual(result["type"], "sse") + self.assertNotIn("name", result) + self.assertNotIn("command", result) + + +@pytest.mark.skip(reason=DEPRECATION_REASON) +class TestGeminiAdapterSerialization(unittest.TestCase): + """Integration tests for Gemini adapter serialization.""" + + def test_AS03_gemini_stdio_serialization(self): + """AS-03: Gemini stdio config serializes correctly.""" + config = MCPServerConfig( + name="gemini-server", + command="npx", + args=["mcp-server"], + cwd="/workspace", + timeout=30000, + ) + + adapter = GeminiAdapter() + result = adapter.serialize(config) + + self.assertEqual(result["command"], "npx") + self.assertEqual(result["args"], ["mcp-server"]) + self.assertEqual(result["cwd"], "/workspace") + self.assertEqual(result["timeout"], 30000) + self.assertNotIn("name", result) + self.assertNotIn("type", result) + + def test_AS04_gemini_http_serialization(self): + """AS-04: Gemini HTTP config serializes correctly.""" + config = MCPServerConfig( + name="gemini-http", + httpUrl="https://api.example.com/http", + trust=True, + ) + + adapter = GeminiAdapter() + result = adapter.serialize(config) + + self.assertEqual(result["httpUrl"], "https://api.example.com/http") + self.assertEqual(result["trust"], True) + self.assertNotIn("name", result) + self.assertNotIn("type", result) + + +@pytest.mark.skip(reason=DEPRECATION_REASON) +class TestVSCodeAdapterSerialization(unittest.TestCase): + """Integration tests for VS Code adapter serialization.""" + + def test_AS05_vscode_with_envfile(self): + """AS-05: VS Code config with envFile serializes correctly.""" + config = MCPServerConfig( + name="vscode-server", + command="node", + args=["server.js"], + envFile=".env", + type="stdio", + ) + + adapter = VSCodeAdapter() + result = adapter.serialize(config) + + self.assertEqual(result["command"], "node") + self.assertEqual(result["envFile"], ".env") + self.assertEqual(result["type"], "stdio") + self.assertNotIn("name", result) + + +@pytest.mark.skip(reason=DEPRECATION_REASON) +class TestCodexAdapterSerialization(unittest.TestCase): + """Integration tests for Codex adapter serialization.""" + + def test_AS06_codex_stdio_serialization(self): + """AS-06: Codex stdio config serializes correctly (no type field). + + Note: Codex maps 'args' to 'arguments' and 'headers' to 'http_headers'. + """ + config = MCPServerConfig( + name="codex-server", + command="python", + args=["server.py"], + env={"DEBUG": "true"}, + ) + + adapter = CodexAdapter() + result = adapter.serialize(config) + + self.assertEqual(result["command"], "python") + # Codex uses 'arguments' instead of 'args' + self.assertEqual(result["arguments"], ["server.py"]) + self.assertNotIn("args", result) # Original name should not be present + self.assertEqual(result["env"], {"DEBUG": "true"}) + self.assertNotIn("name", result) + self.assertNotIn("type", result) + + +@pytest.mark.skip(reason=DEPRECATION_REASON) +class TestKiroAdapterSerialization(unittest.TestCase): + """Integration tests for Kiro adapter serialization.""" + + def test_AS07_kiro_stdio_serialization(self): + """AS-07: Kiro stdio config serializes correctly.""" + config = MCPServerConfig( + name="kiro-server", + command="npx", + args=["@modelcontextprotocol/server"], + ) + + adapter = KiroAdapter() + result = adapter.serialize(config) + + self.assertEqual(result["command"], "npx") + self.assertEqual(result["args"], ["@modelcontextprotocol/server"]) + self.assertNotIn("name", result) + self.assertNotIn("type", result) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/integration/mcp/test_cross_host_sync.py b/tests/integration/mcp/test_cross_host_sync.py new file mode 100644 index 0000000..8fe0799 --- /dev/null +++ b/tests/integration/mcp/test_cross_host_sync.py @@ -0,0 +1,90 @@ +"""Data-driven cross-host sync integration tests. + +Tests all host pair combinations (8Γ—8 = 64) using a single generic test +function. Test cases are generated from canonical_configs.json fixture +with metadata derived from fields.py. + +Architecture: + - ONE test function handles ALL 64 combinations + - Assertions verify against fields.py (not hardcoded expectations) + - Adding a host: update fields.py + add fixture entry β†’ tests auto-generated +""" + +from pathlib import Path + +import pytest + +from hatch.mcp_host_config.models import MCPServerConfig +from tests.test_data.mcp_adapters.assertions import ( + assert_excluded_fields_absent, + assert_only_supported_fields, + assert_transport_present, +) +from tests.test_data.mcp_adapters.host_registry import ( + HostRegistry, + generate_sync_test_cases, +) + +try: + from wobble.decorators import integration_test +except ImportError: + + def integration_test(scope="component"): + def decorator(func): + return func + + return decorator + + +# Registry loads fixtures and derives metadata from fields.py +FIXTURES_PATH = ( + Path(__file__).resolve().parents[2] + / "test_data" + / "mcp_adapters" + / "canonical_configs.json" +) +REGISTRY = HostRegistry(FIXTURES_PATH) +SYNC_TEST_CASES = generate_sync_test_cases(REGISTRY) + + +class TestCrossHostSync: + """Cross-host sync tests for all host pair combinations. + + Verifies that serializing a config from one host and re-serializing + it for another host produces valid output per fields.py contracts. + """ + + @pytest.mark.parametrize( + "test_case", + SYNC_TEST_CASES, + ids=lambda tc: tc.test_id, + ) + @integration_test(scope="service") + def test_sync_between_hosts(self, test_case): + """Generic sync test that works for ANY host pair. + + Flow: + 1. Load source config from fixtures + 2. Serialize with source adapter (filter β†’ validate β†’ transform) + 3. Create intermediate MCPServerConfig from serialized output + 4. Serialize with target adapter + 5. Verify output against fields.py contracts + """ + # Load source config from fixtures + source_config = test_case.from_host.load_config() + + # Serialize with source adapter + from_adapter = test_case.from_host.get_adapter() + serialized = from_adapter.serialize(source_config) + + # Create intermediate config from serialized output + intermediate = MCPServerConfig(name="sync-test", **serialized) + + # Serialize with target adapter + to_adapter = test_case.to_host.get_adapter() + result = to_adapter.serialize(intermediate) + + # Property-based assertions (verify against fields.py) + assert_only_supported_fields(result, test_case.to_host) + assert_excluded_fields_absent(result, test_case.to_host) + assert_transport_present(result, test_case.to_host) diff --git a/tests/integration/mcp/test_host_configuration.py b/tests/integration/mcp/test_host_configuration.py new file mode 100644 index 0000000..0346c42 --- /dev/null +++ b/tests/integration/mcp/test_host_configuration.py @@ -0,0 +1,75 @@ +"""Data-driven host configuration integration tests. + +Tests individual host configuration for all 8 hosts using a single generic +test function. Verifies that each host's canonical config serializes correctly +per fields.py contracts. + +Architecture: + - ONE test function handles ALL 8 hosts + - Assertions verify against fields.py (not hardcoded expectations) + - Adding a host: update fields.py + add fixture entry β†’ tests auto-generated +""" + +from pathlib import Path + +import pytest + +from tests.test_data.mcp_adapters.assertions import ( + assert_excluded_fields_absent, + assert_field_mappings_applied, + assert_only_supported_fields, + assert_transport_present, +) +from tests.test_data.mcp_adapters.host_registry import HostRegistry + +try: + from wobble.decorators import integration_test +except ImportError: + + def integration_test(scope="component"): + def decorator(func): + return func + + return decorator + + +# Registry loads fixtures and derives metadata from fields.py +FIXTURES_PATH = ( + Path(__file__).resolve().parents[2] + / "test_data" + / "mcp_adapters" + / "canonical_configs.json" +) +REGISTRY = HostRegistry(FIXTURES_PATH) +ALL_HOSTS = REGISTRY.all_hosts() + + +class TestHostConfiguration: + """Host configuration tests for all hosts. + + Verifies that each host's canonical config serializes correctly, + producing output that satisfies all fields.py contracts. + """ + + @pytest.mark.parametrize("host", ALL_HOSTS, ids=lambda h: h.host_name) + @integration_test(scope="component") + def test_configure_host(self, host): + """Generic configuration test that works for ANY host. + + Flow: + 1. Load canonical config from fixtures + 2. Serialize with host adapter + 3. Verify output against fields.py contracts + """ + # Load canonical config from fixtures + config = host.load_config() + + # Serialize + adapter = host.get_adapter() + result = adapter.serialize(config) + + # Property-based assertions (verify against fields.py) + assert_only_supported_fields(result, host) + assert_excluded_fields_absent(result, host) + assert_transport_present(result, host) + assert_field_mappings_applied(result, host) diff --git a/tests/integration/test_mcp_kiro_integration.py b/tests/integration/test_mcp_kiro_integration.py deleted file mode 100644 index a3336c6..0000000 --- a/tests/integration/test_mcp_kiro_integration.py +++ /dev/null @@ -1,153 +0,0 @@ -""" -Kiro MCP Integration Tests - -End-to-end integration tests combining CLI, model conversion, and strategy operations. -""" - -import unittest -from unittest.mock import patch, MagicMock - -from wobble.decorators import integration_test - -from hatch.cli_hatch import handle_mcp_configure -from hatch.mcp_host_config.models import ( - HOST_MODEL_REGISTRY, - MCPHostType, - MCPServerConfigKiro -) - - -class TestKiroIntegration(unittest.TestCase): - """Test suite for end-to-end Kiro integration.""" - - @integration_test(scope="component") - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - def test_kiro_end_to_end_configuration(self, mock_manager_class): - """Test complete Kiro configuration workflow.""" - # Setup mocks - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_manager.configure_server.return_value = mock_result - - # Execute CLI command with Kiro-specific arguments - result = handle_mcp_configure( - host='kiro', - server_name='augment-server', - command='auggie', - args=['--mcp', '-m', 'default'], - disabled=False, - auto_approve_tools=['codebase-retrieval', 'fetch'], - disable_tools=['dangerous-tool'], - auto_approve=True - ) - - # Verify success - self.assertEqual(result, 0) - - # Verify configuration manager was called - mock_manager.configure_server.assert_called_once() - - # Verify server configuration - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - - # Verify all Kiro-specific fields - self.assertFalse(server_config.disabled) - self.assertEqual(len(server_config.autoApprove), 2) - self.assertEqual(len(server_config.disabledTools), 1) - self.assertIn('codebase-retrieval', server_config.autoApprove) - self.assertIn('dangerous-tool', server_config.disabledTools) - - @integration_test(scope="system") - def test_kiro_host_model_registry_integration(self): - """Test Kiro integration with HOST_MODEL_REGISTRY.""" - # Verify Kiro is in registry - self.assertIn(MCPHostType.KIRO, HOST_MODEL_REGISTRY) - - # Verify correct model class - model_class = HOST_MODEL_REGISTRY[MCPHostType.KIRO] - self.assertEqual(model_class.__name__, "MCPServerConfigKiro") - - # Test model instantiation - model_instance = model_class( - name="test-server", - command="auggie", - disabled=True - ) - self.assertTrue(model_instance.disabled) - - @integration_test(scope="component") - def test_kiro_model_to_strategy_workflow(self): - """Test workflow from model creation to strategy operations.""" - # Import to trigger registration - import hatch.mcp_host_config.strategies - from hatch.mcp_host_config.host_management import MCPHostRegistry - - # Create Kiro model - kiro_model = MCPServerConfigKiro( - name="workflow-test", - command="auggie", - args=["--mcp"], - disabled=False, - autoApprove=["codebase-retrieval"] - ) - - # Get Kiro strategy - strategy = MCPHostRegistry.get_strategy(MCPHostType.KIRO) - - # Verify strategy can validate the model - self.assertTrue(strategy.validate_server_config(kiro_model)) - - # Verify model fields are accessible - self.assertEqual(kiro_model.command, "auggie") - self.assertFalse(kiro_model.disabled) - self.assertIn("codebase-retrieval", kiro_model.autoApprove) - - @integration_test(scope="end_to_end") - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - def test_kiro_complete_lifecycle(self, mock_manager_class): - """Test complete Kiro server lifecycle: create, configure, validate.""" - # Setup mocks - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_manager.configure_server.return_value = mock_result - - # Step 1: Configure server via CLI - result = handle_mcp_configure( - host='kiro', - server_name='lifecycle-test', - command='auggie', - args=['--mcp', '-w', '.'], - disabled=False, - auto_approve_tools=['codebase-retrieval'], - auto_approve=True - ) - - # Verify CLI success - self.assertEqual(result, 0) - - # Step 2: Verify configuration manager interaction - mock_manager.configure_server.assert_called_once() - call_args = mock_manager.configure_server.call_args - - # Step 3: Verify server configuration structure - server_config = call_args.kwargs['server_config'] - self.assertEqual(server_config.name, 'lifecycle-test') - self.assertEqual(server_config.command, 'auggie') - self.assertIn('--mcp', server_config.args) - self.assertIn('-w', server_config.args) - self.assertFalse(server_config.disabled) - self.assertIn('codebase-retrieval', server_config.autoApprove) - - # Step 4: Verify model type - self.assertIsInstance(server_config, MCPServerConfigKiro) - - -if __name__ == '__main__': - unittest.main() \ No newline at end of file diff --git a/tests/regression/__init__.py b/tests/regression/__init__.py index a43416b..edf7812 100644 --- a/tests/regression/__init__.py +++ b/tests/regression/__init__.py @@ -2,4 +2,4 @@ Regression tests for Hatch MCP functionality. These tests validate existing functionality to prevent breaking changes. -""" \ No newline at end of file +""" diff --git a/tests/regression/cli/__init__.py b/tests/regression/cli/__init__.py new file mode 100644 index 0000000..947c46b --- /dev/null +++ b/tests/regression/cli/__init__.py @@ -0,0 +1,16 @@ +"""Regression tests for CLI reporter infrastructure. + +This package contains regression tests for the CLI UX normalization components: +- ResultReporter state management and data integrity +- ConsequenceType enum contracts +- Color enable/disable logic +- Consequence dataclass invariants + +These tests focus on behavioral contracts rather than output format strings, +ensuring the infrastructure works correctly regardless of UX iteration. + +Test Groups: + test_result_reporter.py: ResultReporter state management, Consequence nesting + test_consequence_type.py: ConsequenceType enum completeness and properties + test_color_logic.py: Color enum and enable/disable decision logic +""" diff --git a/tests/regression/cli/test_color_logic.py b/tests/regression/cli/test_color_logic.py new file mode 100644 index 0000000..baa50a0 --- /dev/null +++ b/tests/regression/cli/test_color_logic.py @@ -0,0 +1,274 @@ +"""Regression tests for Color enum and color enable/disable logic. + +This module tests: +- Color enum completeness (all 14 values defined) +- Color enable/disable decision logic (TTY, NO_COLOR) + +Reference: R05 Β§3.4 (05-test_definition_v0.md) + +Test Groups: + TestColorEnum: Color enum completeness and ANSI code format + TestColorsEnabled: Color enable/disable decision logic +""" + +import os +import sys +import unittest +from unittest.mock import patch + + +class TestColorEnum(unittest.TestCase): + """Tests for Color enum completeness and structure. + + Reference: R06 Β§3.1 - Color interface contract + """ + + def test_color_enum_exists(self): + """Color enum should be importable from cli_utils.""" + from hatch.cli.cli_utils import Color + + self.assertTrue(hasattr(Color, "__members__")) + + def test_color_enum_has_bright_colors(self): + """Color enum should have all 6 bright colors for results.""" + from hatch.cli.cli_utils import Color + + bright_colors = ["GREEN", "RED", "YELLOW", "BLUE", "MAGENTA", "CYAN"] + for color_name in bright_colors: + self.assertTrue( + hasattr(Color, color_name), + f"Color enum missing bright color: {color_name}", + ) + + def test_color_enum_has_dim_colors(self): + """Color enum should have all 6 dim colors for prompts.""" + from hatch.cli.cli_utils import Color + + dim_colors = [ + "GREEN_DIM", + "RED_DIM", + "YELLOW_DIM", + "BLUE_DIM", + "MAGENTA_DIM", + "CYAN_DIM", + ] + for color_name in dim_colors: + self.assertTrue( + hasattr(Color, color_name), + f"Color enum missing dim color: {color_name}", + ) + + def test_color_enum_has_utility_colors(self): + """Color enum should have GRAY and RESET utility colors.""" + from hatch.cli.cli_utils import Color + + self.assertTrue(hasattr(Color, "GRAY"), "Color enum missing GRAY") + self.assertTrue(hasattr(Color, "RESET"), "Color enum missing RESET") + + def test_color_enum_total_count(self): + """Color enum should have exactly 15 members.""" + from hatch.cli.cli_utils import Color + + # 6 bright + 6 dim + GRAY + AMBER + RESET = 15 + self.assertEqual(len(Color), 15, f"Expected 15 colors, got {len(Color)}") + + def test_color_values_are_ansi_codes(self): + """Color values should be ANSI escape sequences (16-color or true color).""" + from hatch.cli.cli_utils import Color + + for color in Color: + self.assertTrue( + color.value.startswith("\033["), + f"{color.name} value should start with ANSI escape: {repr(color.value)}", + ) + self.assertTrue( + color.value.endswith("m"), + f"{color.name} value should end with 'm': {repr(color.value)}", + ) + # Verify it's either 16-color or true color format + is_16_color = color.value.startswith( + "\033[" + ) and not color.value.startswith("\033[38;2;") + is_true_color = color.value.startswith("\033[38;2;") + self.assertTrue( + is_16_color or is_true_color or color.name == "RESET", + f"{color.name} should be 16-color or true color format: {repr(color.value)}", + ) + + def test_amber_color_exists(self): + """Color.AMBER should exist for entity highlighting.""" + from hatch.cli.cli_utils import Color + + self.assertTrue( + hasattr(Color, "AMBER"), "Color enum missing AMBER for entity highlighting" + ) + # AMBER should have a valid ANSI value + self.assertTrue( + Color.AMBER.value.startswith("\033["), + f"AMBER value should be ANSI escape: {repr(Color.AMBER.value)}", + ) + + def test_reset_clears_formatting(self): + """RESET should be the standard ANSI reset code.""" + from hatch.cli.cli_utils import Color + + self.assertEqual(Color.RESET.value, "\033[0m") + + +class TestTrueColorDetection(unittest.TestCase): + """Tests for true color (24-bit) terminal detection. + + Reference: R12 Β§7.2 (12-enhancing_colors_v0.md) - True color detection tests + """ + + def test_truecolor_detection_colorterm_truecolor(self): + """True color should be detected when COLORTERM=truecolor.""" + from hatch.cli.cli_utils import _supports_truecolor + + with patch.dict(os.environ, {"COLORTERM": "truecolor"}, clear=True): + self.assertTrue(_supports_truecolor()) + + def test_truecolor_detection_colorterm_24bit(self): + """True color should be detected when COLORTERM=24bit.""" + from hatch.cli.cli_utils import _supports_truecolor + + with patch.dict(os.environ, {"COLORTERM": "24bit"}, clear=True): + self.assertTrue(_supports_truecolor()) + + def test_truecolor_detection_term_program_iterm(self): + """True color should be detected for iTerm.app.""" + from hatch.cli.cli_utils import _supports_truecolor + + with patch.dict(os.environ, {"TERM_PROGRAM": "iTerm.app"}, clear=True): + self.assertTrue(_supports_truecolor()) + + def test_truecolor_detection_term_program_vscode(self): + """True color should be detected for VS Code terminal.""" + from hatch.cli.cli_utils import _supports_truecolor + + with patch.dict(os.environ, {"TERM_PROGRAM": "vscode"}, clear=True): + self.assertTrue(_supports_truecolor()) + + def test_truecolor_detection_windows_terminal(self): + """True color should be detected for Windows Terminal (WT_SESSION).""" + from hatch.cli.cli_utils import _supports_truecolor + + with patch.dict(os.environ, {"WT_SESSION": "some-session-id"}, clear=True): + self.assertTrue(_supports_truecolor()) + + def test_truecolor_detection_fallback_false(self): + """True color should return False when no indicators present.""" + from hatch.cli.cli_utils import _supports_truecolor + + # Clear all true color indicators + clean_env = {} + with patch.dict(os.environ, clean_env, clear=True): + self.assertFalse(_supports_truecolor()) + + +class TestHighlightFunction(unittest.TestCase): + """Tests for highlight() utility function. + + Reference: R12 Β§3.3 (12-enhancing_colors_v0.md) - Bold modifier + """ + + def test_highlight_with_colors_enabled(self): + """highlight() should apply bold + amber when colors enabled.""" + from hatch.cli.cli_utils import highlight, Color + + env_without_no_color = {k: v for k, v in os.environ.items() if k != "NO_COLOR"} + with patch.dict(os.environ, env_without_no_color, clear=True): + with patch.object(sys.stdout, "isatty", return_value=True): + result = highlight("test-entity") + + # Should contain bold escape + self.assertIn("\033[1m", result) + # Should contain amber color + self.assertIn(Color.AMBER.value, result) + # Should contain reset + self.assertIn(Color.RESET.value, result) + # Should contain the text + self.assertIn("test-entity", result) + + def test_highlight_with_colors_disabled(self): + """highlight() should return plain text when colors disabled.""" + from hatch.cli.cli_utils import highlight + + with patch.dict(os.environ, {"NO_COLOR": "1"}): + result = highlight("test-entity") + + # Should be plain text without ANSI codes + self.assertEqual(result, "test-entity") + self.assertNotIn("\033[", result) + + def test_highlight_non_tty(self): + """highlight() should return plain text in non-TTY mode.""" + from hatch.cli.cli_utils import highlight + + env_without_no_color = {k: v for k, v in os.environ.items() if k != "NO_COLOR"} + with patch.dict(os.environ, env_without_no_color, clear=True): + with patch.object(sys.stdout, "isatty", return_value=False): + result = highlight("test-entity") + + # Should be plain text + self.assertEqual(result, "test-entity") + + +class TestColorsEnabled(unittest.TestCase): + """Tests for color enable/disable decision logic. + + Reference: R05 Β§3.4 - Color Enable/Disable Logic test group + """ + + def test_colors_disabled_when_no_color_set(self): + """Colors should be disabled when NO_COLOR=1.""" + from hatch.cli.cli_utils import _colors_enabled + + with patch.dict(os.environ, {"NO_COLOR": "1"}): + self.assertFalse(_colors_enabled()) + + def test_colors_disabled_when_no_color_truthy(self): + """Colors should be disabled when NO_COLOR=true.""" + from hatch.cli.cli_utils import _colors_enabled + + with patch.dict(os.environ, {"NO_COLOR": "true"}): + self.assertFalse(_colors_enabled()) + + def test_colors_enabled_when_no_color_empty(self): + """Colors should be enabled when NO_COLOR is empty string (if TTY).""" + from hatch.cli.cli_utils import _colors_enabled + + with patch.dict(os.environ, {"NO_COLOR": ""}, clear=False): + with patch.object(sys.stdout, "isatty", return_value=True): + self.assertTrue(_colors_enabled()) + + def test_colors_enabled_when_no_color_unset(self): + """Colors should be enabled when NO_COLOR is not set (if TTY).""" + from hatch.cli.cli_utils import _colors_enabled + + env_without_no_color = {k: v for k, v in os.environ.items() if k != "NO_COLOR"} + with patch.dict(os.environ, env_without_no_color, clear=True): + with patch.object(sys.stdout, "isatty", return_value=True): + self.assertTrue(_colors_enabled()) + + def test_colors_disabled_when_not_tty(self): + """Colors should be disabled when stdout is not a TTY.""" + from hatch.cli.cli_utils import _colors_enabled + + env_without_no_color = {k: v for k, v in os.environ.items() if k != "NO_COLOR"} + with patch.dict(os.environ, env_without_no_color, clear=True): + with patch.object(sys.stdout, "isatty", return_value=False): + self.assertFalse(_colors_enabled()) + + def test_colors_enabled_when_tty_and_no_no_color(self): + """Colors should be enabled when TTY and NO_COLOR not set.""" + from hatch.cli.cli_utils import _colors_enabled + + env_without_no_color = {k: v for k, v in os.environ.items() if k != "NO_COLOR"} + with patch.dict(os.environ, env_without_no_color, clear=True): + with patch.object(sys.stdout, "isatty", return_value=True): + self.assertTrue(_colors_enabled()) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/regression/cli/test_consequence_type.py b/tests/regression/cli/test_consequence_type.py new file mode 100644 index 0000000..3f321f3 --- /dev/null +++ b/tests/regression/cli/test_consequence_type.py @@ -0,0 +1,301 @@ +"""Regression tests for ConsequenceType enum. + +This module tests: +- ConsequenceType enum completeness (all 16 types defined) +- Tense-aware label properties (prompt_label, result_label) +- Color properties (prompt_color, result_color) +- Irregular verb handling (SET, EXISTS, UNCHANGED) + +Reference: R05 Β§3.2 (05-test_definition_v0.md) +Reference: R06 Β§3.2 (06-dependency_analysis_v0.md) +Reference: R03 Β§2 (03-mutation_output_specification_v0.md) +""" + +import unittest + + +class TestConsequenceTypeEnum(unittest.TestCase): + """Tests for ConsequenceType enum completeness and structure. + + Reference: R06 Β§3.2 - ConsequenceType interface contract + """ + + def test_consequence_type_enum_exists(self): + """ConsequenceType enum should be importable from cli_utils.""" + from hatch.cli.cli_utils import ConsequenceType + + self.assertTrue(hasattr(ConsequenceType, "__members__")) + + def test_consequence_type_has_all_constructive_types(self): + """ConsequenceType should have all constructive action types (Green).""" + from hatch.cli.cli_utils import ConsequenceType + + constructive_types = ["CREATE", "ADD", "CONFIGURE", "INSTALL", "INITIALIZE"] + for type_name in constructive_types: + self.assertTrue( + hasattr(ConsequenceType, type_name), + f"ConsequenceType missing constructive type: {type_name}", + ) + + def test_consequence_type_has_recovery_type(self): + """ConsequenceType should have RESTORE recovery type (Blue).""" + from hatch.cli.cli_utils import ConsequenceType + + self.assertTrue(hasattr(ConsequenceType, "RESTORE")) + + def test_consequence_type_has_all_destructive_types(self): + """ConsequenceType should have all destructive action types (Red).""" + from hatch.cli.cli_utils import ConsequenceType + + destructive_types = ["REMOVE", "DELETE", "CLEAN"] + for type_name in destructive_types: + self.assertTrue( + hasattr(ConsequenceType, type_name), + f"ConsequenceType missing destructive type: {type_name}", + ) + + def test_consequence_type_has_all_modification_types(self): + """ConsequenceType should have all modification action types (Yellow).""" + from hatch.cli.cli_utils import ConsequenceType + + modification_types = ["SET", "UPDATE"] + for type_name in modification_types: + self.assertTrue( + hasattr(ConsequenceType, type_name), + f"ConsequenceType missing modification type: {type_name}", + ) + + def test_consequence_type_has_transfer_type(self): + """ConsequenceType should have SYNC transfer type (Magenta).""" + from hatch.cli.cli_utils import ConsequenceType + + self.assertTrue(hasattr(ConsequenceType, "SYNC")) + + def test_consequence_type_has_informational_type(self): + """ConsequenceType should have VALIDATE informational type (Cyan).""" + from hatch.cli.cli_utils import ConsequenceType + + self.assertTrue(hasattr(ConsequenceType, "VALIDATE")) + + def test_consequence_type_has_all_noop_types(self): + """ConsequenceType should have all no-op action types (Gray).""" + from hatch.cli.cli_utils import ConsequenceType + + noop_types = ["SKIP", "EXISTS", "UNCHANGED"] + for type_name in noop_types: + self.assertTrue( + hasattr(ConsequenceType, type_name), + f"ConsequenceType missing no-op type: {type_name}", + ) + + def test_consequence_type_total_count(self): + """ConsequenceType should have exactly 17 members.""" + from hatch.cli.cli_utils import ConsequenceType + + # 5 constructive + 1 recovery + 3 destructive + 2 modification + + # 1 transfer + 2 informational + 3 noop = 17 + self.assertEqual( + len(ConsequenceType), + 17, + f"Expected 17 consequence types, got {len(ConsequenceType)}", + ) + + +class TestConsequenceTypeProperties(unittest.TestCase): + """Tests for ConsequenceType tense-aware properties. + + Reference: R05 Β§3.2 - ConsequenceType Behavior test group + """ + + def test_all_types_have_prompt_label(self): + """All ConsequenceType members should have prompt_label property.""" + from hatch.cli.cli_utils import ConsequenceType + + for ct in ConsequenceType: + self.assertTrue( + hasattr(ct, "prompt_label"), f"{ct.name} missing prompt_label property" + ) + self.assertIsInstance(ct.prompt_label, str) + self.assertTrue( + len(ct.prompt_label) > 0, f"{ct.name}.prompt_label should not be empty" + ) + + def test_all_types_have_result_label(self): + """All ConsequenceType members should have result_label property.""" + from hatch.cli.cli_utils import ConsequenceType + + for ct in ConsequenceType: + self.assertTrue( + hasattr(ct, "result_label"), f"{ct.name} missing result_label property" + ) + self.assertIsInstance(ct.result_label, str) + self.assertTrue( + len(ct.result_label) > 0, f"{ct.name}.result_label should not be empty" + ) + + def test_all_types_have_prompt_color(self): + """All ConsequenceType members should have prompt_color property.""" + from hatch.cli.cli_utils import ConsequenceType, Color + + for ct in ConsequenceType: + self.assertTrue( + hasattr(ct, "prompt_color"), f"{ct.name} missing prompt_color property" + ) + self.assertIsInstance(ct.prompt_color, Color) + + def test_all_types_have_result_color(self): + """All ConsequenceType members should have result_color property.""" + from hatch.cli.cli_utils import ConsequenceType, Color + + for ct in ConsequenceType: + self.assertTrue( + hasattr(ct, "result_color"), f"{ct.name} missing result_color property" + ) + self.assertIsInstance(ct.result_color, Color) + + def test_irregular_verbs_prompt_equals_result(self): + """Irregular verbs (SET, EXISTS, UNCHANGED) should have same prompt and result labels.""" + from hatch.cli.cli_utils import ConsequenceType + + irregular_verbs = [ + ConsequenceType.SET, + ConsequenceType.EXISTS, + ConsequenceType.UNCHANGED, + ConsequenceType.INFO, + ] + + for ct in irregular_verbs: + self.assertEqual( + ct.prompt_label, + ct.result_label, + f"{ct.name} is irregular: prompt_label should equal result_label", + ) + + def test_regular_verbs_result_ends_with_ed(self): + """Regular verbs should have result_label ending with 'ED'.""" + from hatch.cli.cli_utils import ConsequenceType + + # Irregular verbs that don't follow -ED pattern + irregular = {"SET", "EXISTS", "UNCHANGED", "INFO"} + + for ct in ConsequenceType: + if ct.name not in irregular: + self.assertTrue( + ct.result_label.endswith("ED"), + f"{ct.name}.result_label '{ct.result_label}' should end with 'ED'", + ) + + +class TestConsequenceTypeColorSemantics(unittest.TestCase): + """Tests for ConsequenceType color semantic correctness. + + Reference: R03 Β§4.3 - Verb-to-Color mapping + """ + + def test_constructive_types_use_green(self): + """Constructive types should use green colors.""" + from hatch.cli.cli_utils import ConsequenceType, Color + + constructive = [ + ConsequenceType.CREATE, + ConsequenceType.ADD, + ConsequenceType.CONFIGURE, + ConsequenceType.INSTALL, + ConsequenceType.INITIALIZE, + ] + + for ct in constructive: + self.assertEqual( + ct.prompt_color, + Color.GREEN_DIM, + f"{ct.name} prompt_color should be GREEN_DIM", + ) + self.assertEqual( + ct.result_color, Color.GREEN, f"{ct.name} result_color should be GREEN" + ) + + def test_recovery_type_uses_blue(self): + """RESTORE should use blue colors.""" + from hatch.cli.cli_utils import ConsequenceType, Color + + self.assertEqual(ConsequenceType.RESTORE.prompt_color, Color.BLUE_DIM) + self.assertEqual(ConsequenceType.RESTORE.result_color, Color.BLUE) + + def test_destructive_types_use_red(self): + """Destructive types should use red colors.""" + from hatch.cli.cli_utils import ConsequenceType, Color + + destructive = [ + ConsequenceType.REMOVE, + ConsequenceType.DELETE, + ConsequenceType.CLEAN, + ] + + for ct in destructive: + self.assertEqual( + ct.prompt_color, + Color.RED_DIM, + f"{ct.name} prompt_color should be RED_DIM", + ) + self.assertEqual( + ct.result_color, Color.RED, f"{ct.name} result_color should be RED" + ) + + def test_modification_types_use_yellow(self): + """Modification types should use yellow colors.""" + from hatch.cli.cli_utils import ConsequenceType, Color + + modification = [ + ConsequenceType.SET, + ConsequenceType.UPDATE, + ] + + for ct in modification: + self.assertEqual( + ct.prompt_color, + Color.YELLOW_DIM, + f"{ct.name} prompt_color should be YELLOW_DIM", + ) + self.assertEqual( + ct.result_color, + Color.YELLOW, + f"{ct.name} result_color should be YELLOW", + ) + + def test_transfer_type_uses_magenta(self): + """SYNC should use magenta colors.""" + from hatch.cli.cli_utils import ConsequenceType, Color + + self.assertEqual(ConsequenceType.SYNC.prompt_color, Color.MAGENTA_DIM) + self.assertEqual(ConsequenceType.SYNC.result_color, Color.MAGENTA) + + def test_informational_type_uses_cyan(self): + """VALIDATE and INFO should use cyan colors.""" + from hatch.cli.cli_utils import ConsequenceType, Color + + self.assertEqual(ConsequenceType.VALIDATE.prompt_color, Color.CYAN_DIM) + self.assertEqual(ConsequenceType.VALIDATE.result_color, Color.CYAN) + self.assertEqual(ConsequenceType.INFO.prompt_color, Color.CYAN_DIM) + self.assertEqual(ConsequenceType.INFO.result_color, Color.CYAN) + + def test_noop_types_use_gray(self): + """No-op types should use gray colors (same for prompt and result).""" + from hatch.cli.cli_utils import ConsequenceType, Color + + noop = [ + ConsequenceType.SKIP, + ConsequenceType.EXISTS, + ConsequenceType.UNCHANGED, + ] + + for ct in noop: + self.assertEqual( + ct.prompt_color, Color.GRAY, f"{ct.name} prompt_color should be GRAY" + ) + self.assertEqual( + ct.result_color, Color.GRAY, f"{ct.name} result_color should be GRAY" + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/regression/cli/test_error_formatting.py b/tests/regression/cli/test_error_formatting.py new file mode 100644 index 0000000..8907a5a --- /dev/null +++ b/tests/regression/cli/test_error_formatting.py @@ -0,0 +1,319 @@ +"""Regression tests for error formatting infrastructure. + +This module tests: +- HatchArgumentParser error formatting +- ValidationError exception class +- format_validation_error utility +- format_info utility + +Reference: R13 Β§4.2.1 (13-error_message_formatting_v0.md) - HatchArgumentParser +Reference: R13 Β§4.2.2 (13-error_message_formatting_v0.md) - ValidationError +Reference: R13 Β§4.3 (13-error_message_formatting_v0.md) - Utilities +Reference: R13 Β§6.1 (13-error_message_formatting_v0.md) - Argparse error catalog +""" + +import unittest +import subprocess +import sys + + +class TestHatchArgumentParser(unittest.TestCase): + """Tests for HatchArgumentParser error formatting. + + Reference: R13 Β§4.2.1 - Custom ArgumentParser + Reference: R13 Β§6.1 - Argparse error catalog + """ + + def test_argparse_error_has_error_prefix(self): + """Argparse errors should have [ERROR] prefix.""" + from hatch.cli.__main__ import HatchArgumentParser + + # Verify parser class exists + HatchArgumentParser(prog="test") + + # Test via subprocess for proper stderr capture + result = subprocess.run( + [ + sys.executable, + "-c", + "from hatch.cli.__main__ import HatchArgumentParser; " + "p = HatchArgumentParser(); p.error('test error')", + ], + capture_output=True, + text=True, + ) + + self.assertIn("[ERROR]", result.stderr) + + def test_argparse_error_unrecognized_argument(self): + """Unrecognized argument error should have [ERROR] prefix.""" + result = subprocess.run( + [sys.executable, "-m", "hatch.cli", "--invalid-arg"], + capture_output=True, + text=True, + ) + + self.assertIn("[ERROR]", result.stderr) + self.assertIn("unrecognized arguments", result.stderr) + + def test_argparse_error_exit_code_2(self): + """Argparse errors should exit with code 2.""" + result = subprocess.run( + [sys.executable, "-m", "hatch.cli", "--invalid-arg"], + capture_output=True, + text=True, + ) + + self.assertEqual(result.returncode, 2) + + def test_argparse_error_no_ansi_in_pipe(self): + """Argparse errors should not have ANSI codes when piped.""" + result = subprocess.run( + [sys.executable, "-m", "hatch.cli", "--invalid-arg"], + capture_output=True, + text=True, + ) + + # When piped (capture_output=True), stdout is not a TTY + # so ANSI codes should not be present + self.assertNotIn("\033[", result.stderr) + + def test_hatch_argument_parser_class_exists(self): + """HatchArgumentParser class should be importable.""" + from hatch.cli.__main__ import HatchArgumentParser + import argparse + + self.assertTrue(issubclass(HatchArgumentParser, argparse.ArgumentParser)) + + def test_hatch_argument_parser_has_error_method(self): + """HatchArgumentParser should have overridden error method.""" + from hatch.cli.__main__ import HatchArgumentParser + import argparse + + # Verify parser class exists + HatchArgumentParser() + + # Check that error method is overridden (not the same as base class) + self.assertIsNot(HatchArgumentParser.error, argparse.ArgumentParser.error) + + +if __name__ == "__main__": + unittest.main() + + +class TestValidationError(unittest.TestCase): + """Tests for ValidationError exception class. + + Reference: R13 Β§4.2.2 - ValidationError interface + Reference: R13 Β§7.2 - ValidationError contract + """ + + def test_validation_error_attributes(self): + """ValidationError should have message, field, and suggestion attributes.""" + from hatch.cli.cli_utils import ValidationError + + error = ValidationError( + "Test message", field="--host", suggestion="Use valid host" + ) + + self.assertEqual(error.message, "Test message") + self.assertEqual(error.field, "--host") + self.assertEqual(error.suggestion, "Use valid host") + + def test_validation_error_str_returns_message(self): + """ValidationError str() should return message.""" + from hatch.cli.cli_utils import ValidationError + + error = ValidationError("Test message") + self.assertEqual(str(error), "Test message") + + def test_validation_error_optional_field(self): + """ValidationError field should be optional.""" + from hatch.cli.cli_utils import ValidationError + + error = ValidationError("Test message") + self.assertIsNone(error.field) + + def test_validation_error_optional_suggestion(self): + """ValidationError suggestion should be optional.""" + from hatch.cli.cli_utils import ValidationError + + error = ValidationError("Test message") + self.assertIsNone(error.suggestion) + + def test_validation_error_is_exception(self): + """ValidationError should be an Exception subclass.""" + from hatch.cli.cli_utils import ValidationError + + self.assertTrue(issubclass(ValidationError, Exception)) + + def test_validation_error_can_be_raised(self): + """ValidationError should be raisable.""" + from hatch.cli.cli_utils import ValidationError + + with self.assertRaises(ValidationError) as context: + raise ValidationError("Test error", field="--host") + + self.assertEqual(context.exception.message, "Test error") + self.assertEqual(context.exception.field, "--host") + + +class TestFormatValidationError(unittest.TestCase): + """Tests for format_validation_error utility. + + Reference: R13 Β§4.3 - format_validation_error + """ + + def test_format_validation_error_basic(self): + """format_validation_error should print [ERROR] prefix.""" + from hatch.cli.cli_utils import ValidationError, format_validation_error + import io + import sys + + error = ValidationError("Test error message") + + captured = io.StringIO() + sys.stdout = captured + try: + format_validation_error(error) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("[ERROR]", output) + self.assertIn("Test error message", output) + + def test_format_validation_error_with_field(self): + """format_validation_error should print field if provided.""" + from hatch.cli.cli_utils import ValidationError, format_validation_error + import io + import sys + + error = ValidationError("Test error", field="--host") + + captured = io.StringIO() + sys.stdout = captured + try: + format_validation_error(error) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("Field: --host", output) + + def test_format_validation_error_with_suggestion(self): + """format_validation_error should print suggestion if provided.""" + from hatch.cli.cli_utils import ValidationError, format_validation_error + import io + import sys + + error = ValidationError("Test error", suggestion="Use valid host") + + captured = io.StringIO() + sys.stdout = captured + try: + format_validation_error(error) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("Suggestion: Use valid host", output) + + def test_format_validation_error_full(self): + """format_validation_error should print all fields when provided.""" + from hatch.cli.cli_utils import ValidationError, format_validation_error + import io + import sys + + error = ValidationError( + "Invalid host 'vsc'", + field="--host", + suggestion="Supported hosts: claude-desktop, vscode", + ) + + captured = io.StringIO() + sys.stdout = captured + try: + format_validation_error(error) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("[ERROR]", output) + self.assertIn("Invalid host 'vsc'", output) + self.assertIn("Field: --host", output) + self.assertIn("Suggestion: Supported hosts: claude-desktop, vscode", output) + + def test_format_validation_error_no_color_in_non_tty(self): + """format_validation_error should not include ANSI codes when not in TTY.""" + from hatch.cli.cli_utils import ValidationError, format_validation_error + import io + import sys + + error = ValidationError("Test error") + + captured = io.StringIO() + sys.stdout = captured + try: + format_validation_error(error) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertNotIn("\033[", output) + + +class TestFormatInfo(unittest.TestCase): + """Tests for format_info utility. + + Reference: R13-B Β§B.6.2 - Operation cancelled normalization + """ + + def test_format_info_basic(self): + """format_info should print [INFO] prefix.""" + from hatch.cli.cli_utils import format_info + import io + import sys + + captured = io.StringIO() + sys.stdout = captured + try: + format_info("Operation cancelled") + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("[INFO]", output) + self.assertIn("Operation cancelled", output) + + def test_format_info_no_color_in_non_tty(self): + """format_info should not include ANSI codes when not in TTY.""" + from hatch.cli.cli_utils import format_info + import io + import sys + + captured = io.StringIO() + sys.stdout = captured + try: + format_info("Test message") + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertNotIn("\033[", output) + + def test_format_info_output_format(self): + """format_info output should match expected format.""" + from hatch.cli.cli_utils import format_info + import io + import sys + + captured = io.StringIO() + sys.stdout = captured + try: + format_info("Test message") + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue().strip() + self.assertEqual(output, "[INFO] Test message") diff --git a/tests/regression/cli/test_result_reporter.py b/tests/regression/cli/test_result_reporter.py new file mode 100644 index 0000000..c51471a --- /dev/null +++ b/tests/regression/cli/test_result_reporter.py @@ -0,0 +1,606 @@ +"""Regression tests for Consequence dataclass and ResultReporter class. + +This module tests: +- Consequence dataclass invariants and nesting support +- ResultReporter state management and consequence tracking +- ResultReporter mode flags (dry_run, command_name) + +Reference: R05 Β§3.3 (05-test_definition_v0.md) - Nested Consequence Invariants +Reference: R05 Β§3.2 (05-test_definition_v0.md) - ResultReporter State Management +Reference: R06 Β§3.3, Β§3.4 (06-dependency_analysis_v0.md) +""" + +import unittest + + +class TestConsequence(unittest.TestCase): + """Tests for Consequence dataclass invariants. + + Reference: R06 Β§3.3 - Consequence interface contract + Reference: R04 Β§5.1 - Consequence data model invariants + """ + + def test_consequence_dataclass_exists(self): + """Consequence dataclass should be importable from cli_utils.""" + from hatch.cli.cli_utils import Consequence + + self.assertTrue(hasattr(Consequence, "__dataclass_fields__")) + + def test_consequence_accepts_type_and_message(self): + """Consequence should accept type and message arguments.""" + from hatch.cli.cli_utils import Consequence, ConsequenceType + + c = Consequence(type=ConsequenceType.CREATE, message="Test resource") + self.assertEqual(c.type, ConsequenceType.CREATE) + self.assertEqual(c.message, "Test resource") + + def test_consequence_accepts_children_list(self): + """Consequence should accept children list argument.""" + from hatch.cli.cli_utils import Consequence, ConsequenceType + + child1 = Consequence(type=ConsequenceType.UPDATE, message="field1: a β†’ b") + child2 = Consequence(type=ConsequenceType.SKIP, message="field2: unsupported") + + parent = Consequence( + type=ConsequenceType.CONFIGURE, + message="Server 'test'", + children=[child1, child2], + ) + + self.assertEqual(len(parent.children), 2) + self.assertEqual(parent.children[0], child1) + self.assertEqual(parent.children[1], child2) + + def test_consequence_default_children_is_empty_list(self): + """Consequence should have empty list as default children.""" + from hatch.cli.cli_utils import Consequence, ConsequenceType + + c = Consequence(type=ConsequenceType.CREATE, message="Test") + self.assertEqual(c.children, []) + self.assertIsInstance(c.children, list) + + def test_consequence_children_are_consequence_instances(self): + """Children should be Consequence instances.""" + from hatch.cli.cli_utils import Consequence, ConsequenceType + + child = Consequence(type=ConsequenceType.UPDATE, message="child") + parent = Consequence( + type=ConsequenceType.CONFIGURE, message="parent", children=[child] + ) + + self.assertIsInstance(parent.children[0], Consequence) + + def test_consequence_children_default_not_shared(self): + """Each Consequence should have its own children list (no shared mutable default).""" + from hatch.cli.cli_utils import Consequence, ConsequenceType + + c1 = Consequence(type=ConsequenceType.CREATE, message="First") + c2 = Consequence(type=ConsequenceType.CREATE, message="Second") + + # Modify c1's children + c1.children.append(Consequence(type=ConsequenceType.UPDATE, message="child")) + + # c2's children should still be empty + self.assertEqual(len(c2.children), 0) + + +class TestResultReporter(unittest.TestCase): + """Tests for ResultReporter state management. + + Reference: R05 Β§3.2 - ResultReporter State Management test group + Reference: R06 Β§3.4 - ResultReporter interface contract + """ + + def test_result_reporter_exists(self): + """ResultReporter class should be importable from cli_utils.""" + from hatch.cli.cli_utils import ResultReporter + + self.assertTrue(callable(ResultReporter)) + + def test_result_reporter_accepts_command_name(self): + """ResultReporter should accept command_name argument.""" + from hatch.cli.cli_utils import ResultReporter + + reporter = ResultReporter(command_name="hatch env create") + self.assertEqual(reporter.command_name, "hatch env create") + + def test_result_reporter_command_name_stored(self): + """ResultReporter should store command_name correctly.""" + from hatch.cli.cli_utils import ResultReporter + + reporter = ResultReporter("test-cmd") + self.assertEqual(reporter.command_name, "test-cmd") + + def test_result_reporter_dry_run_default_false(self): + """ResultReporter dry_run should default to False.""" + from hatch.cli.cli_utils import ResultReporter + + reporter = ResultReporter("test") + self.assertFalse(reporter.dry_run) + + def test_result_reporter_dry_run_stored(self): + """ResultReporter should store dry_run flag correctly.""" + from hatch.cli.cli_utils import ResultReporter + + reporter = ResultReporter("test", dry_run=True) + self.assertTrue(reporter.dry_run) + + def test_result_reporter_empty_consequences(self): + """Empty reporter should have empty consequences list.""" + from hatch.cli.cli_utils import ResultReporter + + reporter = ResultReporter("test") + self.assertEqual(reporter.consequences, []) + self.assertIsInstance(reporter.consequences, list) + + def test_result_reporter_add_consequence(self): + """ResultReporter.add() should add consequence to list.""" + from hatch.cli.cli_utils import ResultReporter, ConsequenceType + + reporter = ResultReporter("test") + reporter.add(ConsequenceType.CREATE, "Environment 'dev'") + + self.assertEqual(len(reporter.consequences), 1) + + def test_result_reporter_consequences_tracked_in_order(self): + """Consequences should be tracked in order of add() calls.""" + from hatch.cli.cli_utils import ResultReporter, ConsequenceType + + reporter = ResultReporter("test") + reporter.add(ConsequenceType.CREATE, "First") + reporter.add(ConsequenceType.REMOVE, "Second") + reporter.add(ConsequenceType.UPDATE, "Third") + + self.assertEqual(len(reporter.consequences), 3) + self.assertEqual(reporter.consequences[0].message, "First") + self.assertEqual(reporter.consequences[1].message, "Second") + self.assertEqual(reporter.consequences[2].message, "Third") + + def test_result_reporter_consequence_data_preserved(self): + """Consequence type and message should be preserved.""" + from hatch.cli.cli_utils import ResultReporter, ConsequenceType + + reporter = ResultReporter("test") + reporter.add(ConsequenceType.CONFIGURE, "Server 'weather'") + + c = reporter.consequences[0] + self.assertEqual(c.type, ConsequenceType.CONFIGURE) + self.assertEqual(c.message, "Server 'weather'") + + def test_result_reporter_add_with_children(self): + """ResultReporter.add() should support children argument.""" + from hatch.cli.cli_utils import ResultReporter, ConsequenceType, Consequence + + reporter = ResultReporter("test") + children = [ + Consequence(type=ConsequenceType.UPDATE, message="field1"), + Consequence(type=ConsequenceType.SKIP, message="field2"), + ] + reporter.add(ConsequenceType.CONFIGURE, "Server", children=children) + + self.assertEqual(len(reporter.consequences[0].children), 2) + + +if __name__ == "__main__": + unittest.main() + + +class TestConversionReportIntegration(unittest.TestCase): + """Tests for ConversionReport β†’ ResultReporter integration. + + Reference: R05 Β§3.5 - ConversionReport Integration test group + Reference: R06 Β§3.5 - add_from_conversion_report interface + Reference: R04 Β§1.2 - field operation β†’ ConsequenceType mapping + """ + + def test_add_from_conversion_report_method_exists(self): + """ResultReporter should have add_from_conversion_report method.""" + from hatch.cli.cli_utils import ResultReporter + + reporter = ResultReporter("test") + self.assertTrue(hasattr(reporter, "add_from_conversion_report")) + self.assertTrue(callable(reporter.add_from_conversion_report)) + + def test_updated_maps_to_update_type(self): + """FieldOperation 'UPDATED' should map to ConsequenceType.UPDATE.""" + from hatch.cli.cli_utils import ResultReporter, ConsequenceType + from tests.test_data.fixtures.cli_reporter_fixtures import REPORT_SINGLE_UPDATE + + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_SINGLE_UPDATE) + + # Should have one resource consequence with one child + self.assertEqual(len(reporter.consequences), 1) + self.assertEqual(len(reporter.consequences[0].children), 1) + self.assertEqual( + reporter.consequences[0].children[0].type, ConsequenceType.UPDATE + ) + + def test_unsupported_maps_to_skip_type(self): + """FieldOperation 'UNSUPPORTED' should map to ConsequenceType.SKIP.""" + from hatch.cli.cli_utils import ResultReporter, ConsequenceType + from tests.test_data.fixtures.cli_reporter_fixtures import ( + REPORT_ALL_UNSUPPORTED, + ) + + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_ALL_UNSUPPORTED) + + # All children should be SKIP type + for child in reporter.consequences[0].children: + self.assertEqual(child.type, ConsequenceType.SKIP) + + def test_unchanged_maps_to_unchanged_type(self): + """FieldOperation 'UNCHANGED' should map to ConsequenceType.UNCHANGED.""" + from hatch.cli.cli_utils import ResultReporter, ConsequenceType + from tests.test_data.fixtures.cli_reporter_fixtures import REPORT_ALL_UNCHANGED + + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_ALL_UNCHANGED) + + # All children should be UNCHANGED type + for child in reporter.consequences[0].children: + self.assertEqual(child.type, ConsequenceType.UNCHANGED) + + def test_field_name_preserved_in_mapping(self): + """Field name should be preserved in consequence message.""" + from hatch.cli.cli_utils import ResultReporter + from tests.test_data.fixtures.cli_reporter_fixtures import REPORT_SINGLE_UPDATE + + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_SINGLE_UPDATE) + + child_message = reporter.consequences[0].children[0].message + self.assertIn("command", child_message) + + def test_old_new_values_preserved(self): + """Old and new values should be preserved in consequence message.""" + from hatch.cli.cli_utils import ResultReporter + from tests.test_data.fixtures.cli_reporter_fixtures import ( + REPORT_MIXED_OPERATIONS, + ) + + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_MIXED_OPERATIONS) + + # Find the command field child (first one with UPDATED) + command_child = reporter.consequences[0].children[0] + self.assertIn("node", command_child.message) # old value + self.assertIn("python", command_child.message) # new value + + def test_all_fields_mapped_no_data_loss(self): + """All field operations should be mapped (no data loss).""" + from hatch.cli.cli_utils import ResultReporter + from tests.test_data.fixtures.cli_reporter_fixtures import ( + REPORT_MIXED_OPERATIONS, + ) + + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_MIXED_OPERATIONS) + + # REPORT_MIXED_OPERATIONS has 4 field operations + self.assertEqual(len(reporter.consequences[0].children), 4) + + def test_empty_conversion_report_handled(self): + """Empty ConversionReport should not raise exception.""" + from hatch.cli.cli_utils import ResultReporter + from tests.test_data.fixtures.cli_reporter_fixtures import REPORT_EMPTY_FIELDS + + reporter = ResultReporter("test") + # Should not raise + reporter.add_from_conversion_report(REPORT_EMPTY_FIELDS) + + # Should have resource consequence with no children + self.assertEqual(len(reporter.consequences), 1) + self.assertEqual(len(reporter.consequences[0].children), 0) + + def test_resource_consequence_type_from_operation(self): + """Resource consequence type should be derived from report.operation.""" + from hatch.cli.cli_utils import ResultReporter, ConsequenceType + from tests.test_data.fixtures.cli_reporter_fixtures import ( + REPORT_SINGLE_UPDATE, # operation="create" + REPORT_MIXED_OPERATIONS, # operation="update" + ) + + reporter1 = ResultReporter("test") + reporter1.add_from_conversion_report(REPORT_SINGLE_UPDATE) + # "create" operation should map to CONFIGURE (for MCP server creation) + self.assertIn( + reporter1.consequences[0].type, + [ConsequenceType.CONFIGURE, ConsequenceType.CREATE], + ) + + reporter2 = ResultReporter("test") + reporter2.add_from_conversion_report(REPORT_MIXED_OPERATIONS) + # "update" operation should map to CONFIGURE or UPDATE + self.assertIn( + reporter2.consequences[0].type, + [ConsequenceType.CONFIGURE, ConsequenceType.UPDATE], + ) + + def test_server_name_in_resource_message(self): + """Server name should appear in resource consequence message.""" + from hatch.cli.cli_utils import ResultReporter + from tests.test_data.fixtures.cli_reporter_fixtures import ( + REPORT_MIXED_OPERATIONS, + ) + + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_MIXED_OPERATIONS) + + self.assertIn("weather-server", reporter.consequences[0].message) + + def test_target_host_in_resource_message(self): + """Target host should appear in resource consequence message.""" + from hatch.cli.cli_utils import ResultReporter + from tests.test_data.fixtures.cli_reporter_fixtures import ( + REPORT_MIXED_OPERATIONS, + ) + + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_MIXED_OPERATIONS) + + self.assertIn("cursor", reporter.consequences[0].message.lower()) + + +class TestReportError(unittest.TestCase): + """Tests for ResultReporter.report_error() method. + + Reference: R13 Β§4.2.3 (13-error_message_formatting_v0.md) + Reference: R13 Β§7 - Contracts & Invariants + """ + + def test_report_error_basic(self): + """report_error should print [ERROR] prefix with summary.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + # Capture stdout + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_error("Test error message") + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("[ERROR]", output) + self.assertIn("Test error message", output) + + def test_report_error_with_details(self): + """report_error should print details with indentation.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_error("Summary", details=["Detail 1", "Detail 2"]) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("Detail 1", output) + self.assertIn("Detail 2", output) + # Details should be indented (2 spaces) + self.assertIn(" Detail 1", output) + + def test_report_error_empty_summary_no_output(self): + """report_error with empty summary should produce no output.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_error("") + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertEqual(output, "") + + def test_report_error_no_color_in_non_tty(self): + """report_error should not include ANSI codes when not in TTY.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + # StringIO is not a TTY, so colors should be disabled + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_error("Test error") + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + # Should not contain ANSI escape codes + self.assertNotIn("\033[", output) + + def test_report_error_none_details_handled(self): + """report_error should handle None details gracefully.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_error("Test error", details=None) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("[ERROR]", output) + self.assertIn("Test error", output) + + +class TestReportPartialSuccess(unittest.TestCase): + """Tests for ResultReporter.report_partial_success() method. + + Reference: R13 Β§4.2.3 (13-error_message_formatting_v0.md) + Reference: R13 Β§7 - Contracts & Invariants + """ + + def test_report_partial_success_basic(self): + """report_partial_success should print [WARNING] prefix.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_partial_success( + "Test summary", ["ok"], [("fail", "reason")] + ) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("[WARNING]", output) + self.assertIn("Test summary", output) + + def test_report_partial_success_unicode_symbols(self): + """report_partial_success should use βœ“/βœ— symbols in UTF-8 terminals.""" + from hatch.cli.cli_utils import ResultReporter, _supports_unicode + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_partial_success("Test", ["success"], [("fail", "reason")]) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + if _supports_unicode(): + self.assertIn("βœ“", output) + self.assertIn("βœ—", output) + else: + self.assertIn("+", output) + self.assertIn("x", output) + + def test_report_partial_success_ascii_fallback(self): + """report_partial_success should use +/x in non-UTF8 terminals.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + import unittest.mock as mock + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + # Mock _supports_unicode to return False + with mock.patch( + "hatch.cli.cli_utils._supports_unicode", return_value=False + ): + reporter.report_partial_success( + "Test", ["success"], [("fail", "reason")] + ) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("+", output) + self.assertIn("x", output) + + def test_report_partial_success_summary_line(self): + """report_partial_success should include summary line with counts.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_partial_success( + "Test", + ["ok1", "ok2"], + [("fail1", "r1"), ("fail2", "r2"), ("fail3", "r3")], + ) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("Summary: 2/5 succeeded", output) + + def test_report_partial_success_no_color_in_non_tty(self): + """report_partial_success should not include ANSI codes when not in TTY.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_partial_success("Test", ["ok"], [("fail", "reason")]) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertNotIn("\033[", output) + + def test_report_partial_success_failure_reason_shown(self): + """report_partial_success should show failure reason after colon.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_partial_success( + "Test", [], [("cursor", "Config file not found")] + ) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("cursor: Config file not found", output) + + def test_report_partial_success_empty_lists(self): + """report_partial_success should handle empty success/failure lists.""" + from hatch.cli.cli_utils import ResultReporter + import io + import sys + + reporter = ResultReporter("test") + + captured = io.StringIO() + sys.stdout = captured + try: + reporter.report_partial_success("Test", [], []) + finally: + sys.stdout = sys.__stdout__ + + output = captured.getvalue() + self.assertIn("[WARNING]", output) + self.assertIn("Summary: 0/0 succeeded", output) diff --git a/tests/regression/cli/test_table_formatter.py b/tests/regression/cli/test_table_formatter.py new file mode 100644 index 0000000..6ca3198 --- /dev/null +++ b/tests/regression/cli/test_table_formatter.py @@ -0,0 +1,209 @@ +"""Regression tests for TableFormatter class. + +Tests focus on behavioral contracts for table rendering: +- Column alignment (left, right, center) +- Auto-width calculation +- Header and separator rendering +- Row data handling + +Reference: R02 Β§5 (02-list_output_format_specification_v2.md) +Reference: R06 Β§3.6 (06-dependency_analysis_v0.md) +""" + + +class TestColumnDef: + """Tests for ColumnDef dataclass.""" + + def test_column_def_has_required_fields(self): + """ColumnDef must have name, width, and align fields.""" + from hatch.cli.cli_utils import ColumnDef + + col = ColumnDef(name="Test", width=10) + assert col.name == "Test" + assert col.width == 10 + assert col.align == "left" # Default alignment + + def test_column_def_accepts_auto_width(self): + """ColumnDef width can be 'auto' for auto-calculation.""" + from hatch.cli.cli_utils import ColumnDef + + col = ColumnDef(name="Test", width="auto") + assert col.width == "auto" + + def test_column_def_accepts_alignment_options(self): + """ColumnDef supports left, right, and center alignment.""" + from hatch.cli.cli_utils import ColumnDef + + left = ColumnDef(name="Left", width=10, align="left") + right = ColumnDef(name="Right", width=10, align="right") + center = ColumnDef(name="Center", width=10, align="center") + + assert left.align == "left" + assert right.align == "right" + assert center.align == "center" + + +class TestTableFormatter: + """Tests for TableFormatter class.""" + + def test_table_formatter_accepts_column_definitions(self): + """TableFormatter initializes with column definitions.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ + ColumnDef(name="Name", width=20), + ColumnDef(name="Value", width=10), + ] + formatter = TableFormatter(columns) + assert formatter is not None + + def test_add_row_stores_data(self): + """add_row stores row data for rendering.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Col1", width=10)] + formatter = TableFormatter(columns) + formatter.add_row(["value1"]) + formatter.add_row(["value2"]) + + # Verify rows are stored (implementation detail, but necessary for render) + assert len(formatter._rows) == 2 + + def test_render_produces_string_output(self): + """render() returns a string with table content.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Name", width=10)] + formatter = TableFormatter(columns) + formatter.add_row(["Test"]) + + output = formatter.render() + assert isinstance(output, str) + assert len(output) > 0 + + def test_render_includes_header_row(self): + """Rendered output includes column headers.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ + ColumnDef(name="Name", width=15), + ColumnDef(name="Status", width=10), + ] + formatter = TableFormatter(columns) + formatter.add_row(["test-item", "active"]) + + output = formatter.render() + assert "Name" in output + assert "Status" in output + + def test_render_includes_separator_line(self): + """Rendered output includes separator line after headers.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Name", width=10)] + formatter = TableFormatter(columns) + formatter.add_row(["Test"]) + + output = formatter.render() + # Separator uses box-drawing character or dashes + assert "─" in output or "-" in output + + def test_render_includes_data_rows(self): + """Rendered output includes all added data rows.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Item", width=15)] + formatter = TableFormatter(columns) + formatter.add_row(["first-item"]) + formatter.add_row(["second-item"]) + formatter.add_row(["third-item"]) + + output = formatter.render() + assert "first-item" in output + assert "second-item" in output + assert "third-item" in output + + def test_left_alignment_pads_right(self): + """Left-aligned columns pad values on the right.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Name", width=10, align="left")] + formatter = TableFormatter(columns) + formatter.add_row(["abc"]) + + output = formatter.render() + lines = output.strip().split("\n") + # Find data row (skip header and separator) + data_line = lines[-1] + # Left-aligned: value followed by spaces + assert "abc" in data_line + + def test_right_alignment_pads_left(self): + """Right-aligned columns pad values on the left.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Count", width=10, align="right")] + formatter = TableFormatter(columns) + formatter.add_row(["42"]) + + output = formatter.render() + lines = output.strip().split("\n") + data_line = lines[-1] + # Right-aligned: spaces followed by value + assert "42" in data_line + + def test_auto_width_calculates_from_content(self): + """Auto width calculates based on header and data content.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Name", width="auto")] + formatter = TableFormatter(columns) + formatter.add_row(["short"]) + formatter.add_row(["much-longer-value"]) + + output = formatter.render() + # Output should accommodate the longest value + assert "much-longer-value" in output + + def test_empty_table_renders_headers_only(self): + """Table with no rows renders headers and separator.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Empty", width=10)] + formatter = TableFormatter(columns) + + output = formatter.render() + assert "Empty" in output + # Should have header and separator, but no data rows + + def test_multiple_columns_separated(self): + """Multiple columns are visually separated.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ + ColumnDef(name="Col1", width=10), + ColumnDef(name="Col2", width=10), + ColumnDef(name="Col3", width=10), + ] + formatter = TableFormatter(columns) + formatter.add_row(["a", "b", "c"]) + + output = formatter.render() + assert "Col1" in output + assert "Col2" in output + assert "Col3" in output + assert "a" in output + assert "b" in output + assert "c" in output + + def test_truncation_with_ellipsis(self): + """Values exceeding column width are truncated with ellipsis.""" + from hatch.cli.cli_utils import TableFormatter, ColumnDef + + columns = [ColumnDef(name="Name", width=8)] + formatter = TableFormatter(columns) + formatter.add_row(["very-long-value-that-exceeds-width"]) + + output = formatter.render() + # Should truncate and add ellipsis + assert "…" in output or "..." in output diff --git a/tests/regression/mcp/__init__.py b/tests/regression/mcp/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/regression/mcp/test_field_filtering.py b/tests/regression/mcp/test_field_filtering.py new file mode 100644 index 0000000..ab13b2e --- /dev/null +++ b/tests/regression/mcp/test_field_filtering.py @@ -0,0 +1,172 @@ +"""Regression tests for field filtering (name/type exclusion). + +DEPRECATED: This test file is deprecated and will be removed in v0.9.0. +Replaced by: tests/regression/mcp/test_field_filtering_v2.py +Reason: Migrating to data-driven test architecture (see 01-test-definition_v0.md) + +Test IDs: RF-01 to RF-07 (per 02-test_architecture_rebuild_v0.md) +Scope: Prevent `name` and `type` field leakage in serialized output. +""" + +import unittest + +import pytest + +from hatch.mcp_host_config.models import MCPServerConfig +from hatch.mcp_host_config.adapters import ( + ClaudeAdapter, + CodexAdapter, + CursorAdapter, + GeminiAdapter, + KiroAdapter, + VSCodeAdapter, +) + +DEPRECATION_REASON = ( + "Deprecated - replaced by data-driven tests (test_field_filtering_v2.py)" +) + + +@pytest.mark.skip(reason=DEPRECATION_REASON) +class TestFieldFiltering(unittest.TestCase): + """Regression tests for field filtering (RF-01 to RF-07). + + These tests ensure: + - `name` is NEVER in serialized output (it's Hatch metadata, not host config) + - `type` behavior varies by host (some include, some exclude) + """ + + def setUp(self): + """Create test configs for use across tests.""" + # Config WITH type (for hosts that support type field) + self.stdio_config_with_type = MCPServerConfig( + name="test-server", + command="python", + args=["server.py"], + type="stdio", + ) + + # Config WITHOUT type (for hosts that don't support type field) + self.stdio_config_no_type = MCPServerConfig( + name="test-server", + command="python", + args=["server.py"], + ) + + self.sse_config_with_type = MCPServerConfig( + name="sse-server", + url="https://example.com/mcp", + type="sse", + ) + + self.sse_config_no_type = MCPServerConfig( + name="sse-server", + url="https://example.com/mcp", + ) + + def test_RF01_name_never_in_gemini_output(self): + """RF-01: `name` never appears in Gemini serialized output.""" + adapter = GeminiAdapter() + result = adapter.serialize(self.stdio_config_no_type) + + self.assertNotIn("name", result) + + def test_RF02_name_never_in_claude_output(self): + """RF-02: `name` never appears in Claude serialized output.""" + adapter = ClaudeAdapter() + result = adapter.serialize(self.stdio_config_with_type) + + self.assertNotIn("name", result) + + def test_RF03_type_not_in_gemini_output(self): + """RF-03: `type` should NOT be in Gemini output. + + Gemini's config format infers type from the presence of + command/url/httpUrl fields. + """ + adapter = GeminiAdapter() + result = adapter.serialize(self.stdio_config_no_type) + + self.assertNotIn("type", result) + + def test_RF04_type_not_in_kiro_output(self): + """RF-04: `type` should NOT be in Kiro output. + + Kiro's config format infers type from the presence of + command/url fields. + """ + adapter = KiroAdapter() + result = adapter.serialize(self.stdio_config_no_type) + + self.assertNotIn("type", result) + + def test_RF05_type_not_in_codex_output(self): + """RF-05: `type` should NOT be in Codex output. + + Codex TOML format doesn't use type field - it uses section headers. + """ + adapter = CodexAdapter() + result = adapter.serialize(self.stdio_config_no_type) + + self.assertNotIn("type", result) + + def test_RF06_type_IS_in_claude_output(self): + """RF-06: `type` SHOULD be in Claude output. + + Claude Desktop/Code explicitly uses the type field for transport. + """ + adapter = ClaudeAdapter() + result = adapter.serialize(self.stdio_config_with_type) + + self.assertIn("type", result) + self.assertEqual(result["type"], "stdio") + + def test_RF07_type_IS_in_vscode_output(self): + """RF-07: `type` SHOULD be in VS Code output. + + VS Code explicitly uses the type field for transport. + """ + adapter = VSCodeAdapter() + result = adapter.serialize(self.stdio_config_with_type) + + self.assertIn("type", result) + self.assertEqual(result["type"], "stdio") + + def test_name_never_in_any_adapter_output(self): + """Comprehensive test: `name` never appears in ANY adapter output. + + Uses appropriate config for each adapter (with/without type field). + """ + type_supporting_adapters = [ + ClaudeAdapter(), + CursorAdapter(), + VSCodeAdapter(), + ] + + type_rejecting_adapters = [ + CodexAdapter(), + GeminiAdapter(), + KiroAdapter(), + ] + + for adapter in type_supporting_adapters: + with self.subTest(adapter=adapter.host_name): + result = adapter.serialize(self.stdio_config_with_type) + self.assertNotIn("name", result) + + for adapter in type_rejecting_adapters: + with self.subTest(adapter=adapter.host_name): + result = adapter.serialize(self.stdio_config_no_type) + self.assertNotIn("name", result) + + def test_cursor_type_behavior(self): + """Test Cursor type field behavior (same as VS Code).""" + adapter = CursorAdapter() + result = adapter.serialize(self.stdio_config_with_type) + + # Cursor should include type like VS Code + self.assertIn("type", result) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/regression/mcp/test_field_filtering_v2.py b/tests/regression/mcp/test_field_filtering_v2.py new file mode 100644 index 0000000..7ba770d --- /dev/null +++ b/tests/regression/mcp/test_field_filtering_v2.py @@ -0,0 +1,123 @@ +"""Data-driven field filtering regression tests. + +Tests that unsupported fields are silently filtered (not rejected) for +every host. Test cases are generated from the set difference between +all possible MCP fields and each host's supported fields. + +Architecture: + - Test cases GENERATED from fields.py set operations + - Adding a field to fields.py: auto-generates filtering tests + - Adding a host: auto-generates all unsupported field tests +""" + +from pathlib import Path + +import pytest + +from hatch.mcp_host_config.models import MCPServerConfig +from tests.test_data.mcp_adapters.assertions import assert_unsupported_field_absent +from tests.test_data.mcp_adapters.host_registry import ( + HostRegistry, + generate_unsupported_field_test_cases, +) + +try: + from wobble.decorators import regression_test +except ImportError: + + def regression_test(func): + return func + + +# Registry loads fixtures and derives metadata from fields.py +FIXTURES_PATH = ( + Path(__file__).resolve().parents[2] + / "test_data" + / "mcp_adapters" + / "canonical_configs.json" +) +REGISTRY = HostRegistry(FIXTURES_PATH) +FILTER_CASES = generate_unsupported_field_test_cases(REGISTRY) + +# Type-aware test values for MCPServerConfig fields. +# Each field needs a value matching its Pydantic type annotation. +FIELD_TEST_VALUES = { + # String fields + "command": "python", + "url": "http://test.example.com/mcp", + "httpUrl": "http://test.example.com/http", + "type": "stdio", + "cwd": "/tmp/test", + "envFile": ".env.test", + "authProviderType": "oauth2", + "oauth_clientId": "test-client", + "oauth_clientSecret": "test-secret", + "oauth_authorizationUrl": "http://auth.example.com/authorize", + "oauth_tokenUrl": "http://auth.example.com/token", + "oauth_redirectUri": "http://localhost:3000/callback", + "oauth_tokenParamName": "access_token", + "bearer_token_env_var": "BEARER_TOKEN", + # Integer fields + "timeout": 30000, + "startup_timeout_sec": 10, + "tool_timeout_sec": 60, + # Boolean fields + "trust": False, + "oauth_enabled": False, + "disabled": False, + "enabled": True, + # List[str] fields + "args": ["--test"], + "includeTools": ["tool1"], + "excludeTools": ["tool2"], + "oauth_scopes": ["read"], + "oauth_audiences": ["api"], + "autoApprove": ["tool1"], + "disabledTools": ["tool2"], + "env_vars": ["VAR1"], + "enabled_tools": ["tool1"], + "disabled_tools": ["tool2"], + # Dict fields + "env": {"TEST": "value"}, + "headers": {"X-Test": "value"}, + "http_headers": {"X-Test": "value"}, + "env_http_headers": {"X-Auth": "AUTH_TOKEN"}, + # List[Dict] fields + "inputs": [{"id": "key", "type": "promptString"}], +} + + +class TestFieldFiltering: + """Regression tests: unsupported fields are filtered, not rejected. + + For each host, tests every field that the host does NOT support + to verify it is silently removed during serialization. + """ + + @pytest.mark.parametrize( + "test_case", + FILTER_CASES, + ids=lambda tc: tc.test_id, + ) + @regression_test + def test_unsupported_field_filtered(self, test_case): + """Verify unsupported field is filtered, not rejected.""" + host = test_case.host + field_name = test_case.unsupported_field + + # Get type-appropriate test value + test_value = FIELD_TEST_VALUES.get(field_name, "test_value") + + # Create config with the unsupported field + config = MCPServerConfig( + name="test", + command="python", + **{field_name: test_value}, + ) + + # Serialize (should NOT raise error β€” field should be filtered) + adapter = host.get_adapter() + result = adapter.serialize(config) + + # Assert unsupported field is absent from output + assert_unsupported_field_absent(result, host, field_name) diff --git a/tests/regression/mcp/test_validation_bugs.py b/tests/regression/mcp/test_validation_bugs.py new file mode 100644 index 0000000..c8e4199 --- /dev/null +++ b/tests/regression/mcp/test_validation_bugs.py @@ -0,0 +1,116 @@ +"""Validation bug regression tests (data-driven). + +Property-based tests generated from fields.py metadata to prevent +validation bug regressions. Tests verify: +- Tool list coexistence (allowlist + denylist can both be present) +- Transport mutual exclusion (exactly one transport required) + +Architecture: + - Test cases GENERATED from fields.py metadata + - Tests verify PROPERTIES, not specific examples + - Adding a host with tool lists: test case auto-generated +""" + +from pathlib import Path + +import pytest + +from hatch.mcp_host_config.adapters.base import AdapterValidationError +from hatch.mcp_host_config.models import MCPServerConfig +from tests.test_data.mcp_adapters.assertions import assert_tool_lists_coexist +from tests.test_data.mcp_adapters.host_registry import ( + HostRegistry, + generate_validation_test_cases, +) + +try: + from wobble.decorators import regression_test +except ImportError: + + def regression_test(func): + return func + + +# Registry loads fixtures and derives metadata from fields.py +FIXTURES_PATH = ( + Path(__file__).resolve().parents[2] + / "test_data" + / "mcp_adapters" + / "canonical_configs.json" +) +REGISTRY = HostRegistry(FIXTURES_PATH) +VALIDATION_CASES = generate_validation_test_cases(REGISTRY) + +# Split cases by property for separate test functions +TOOL_LIST_CASES = [ + c for c in VALIDATION_CASES if c.property_name == "tool_lists_coexist" +] +TRANSPORT_CASES = [ + c for c in VALIDATION_CASES if c.property_name == "transport_mutual_exclusion" +] + + +class TestToolListCoexistence: + """Regression tests: allowlist and denylist can coexist. + + Per official docs: + - Gemini: excludeTools takes precedence over includeTools + - Codex: disabled_tools applied after enabled_tools + """ + + @pytest.mark.parametrize( + "test_case", + TOOL_LIST_CASES, + ids=lambda tc: tc.test_id, + ) + @regression_test + def test_tool_lists_can_coexist(self, test_case): + """Verify both allowlist and denylist can be present simultaneously.""" + host = test_case.host + tool_config = host.get_tool_list_config() + + # Create config with both allowlist and denylist + config_data = { + "name": "test", + "command": "python", + tool_config["allowlist"]: ["tool1"], + tool_config["denylist"]: ["tool2"], + } + config = MCPServerConfig(**config_data) + + # Serialize (should NOT raise) + adapter = host.get_adapter() + result = adapter.serialize(config) + + # Assert both fields present in output + assert_tool_lists_coexist(result, host) + + +class TestTransportMutualExclusion: + """Regression tests: exactly one transport required. + + All hosts enforce that only one transport method can be specified. + Having both command and url should raise AdapterValidationError. + """ + + @pytest.mark.parametrize( + "test_case", + TRANSPORT_CASES, + ids=lambda tc: tc.test_id, + ) + @regression_test + def test_transport_mutual_exclusion(self, test_case): + """Verify multiple transports are rejected.""" + host = test_case.host + adapter = host.get_adapter() + + # Create config with multiple transports (command + url) + config = MCPServerConfig( + name="test", + command="python", + url="http://test.example.com/mcp", + ) + + # Should raise validation error + with pytest.raises(AdapterValidationError): + adapter.serialize(config) diff --git a/tests/regression/test_mcp_codex_backup_integration.py b/tests/regression/test_mcp_codex_backup_integration.py deleted file mode 100644 index 1737ab0..0000000 --- a/tests/regression/test_mcp_codex_backup_integration.py +++ /dev/null @@ -1,162 +0,0 @@ -""" -Codex MCP Backup Integration Tests - -Tests for Codex TOML backup integration including backup creation, -restoration, and the no_backup parameter. -""" - -import unittest -import tempfile -import tomllib -from pathlib import Path - -from wobble.decorators import regression_test - -from hatch.mcp_host_config.strategies import CodexHostStrategy -from hatch.mcp_host_config.models import MCPServerConfig, HostConfiguration -from hatch.mcp_host_config.backup import MCPHostConfigBackupManager, BackupInfo - - -class TestCodexBackupIntegration(unittest.TestCase): - """Test suite for Codex backup integration.""" - - def setUp(self): - """Set up test environment.""" - self.strategy = CodexHostStrategy() - - @regression_test - def test_write_configuration_creates_backup_by_default(self): - """Test that write_configuration creates backup by default when file exists.""" - with tempfile.TemporaryDirectory() as tmpdir: - config_path = Path(tmpdir) / "config.toml" - backup_dir = Path(tmpdir) / "backups" - - # Create initial config - initial_toml = """[mcp_servers.old-server] -command = "old-command" -""" - config_path.write_text(initial_toml) - - # Create new configuration - new_config = HostConfiguration(servers={ - 'new-server': MCPServerConfig( - command='new-command', - args=['--test'] - ) - }) - - # Patch paths - from unittest.mock import patch - with patch.object(self.strategy, 'get_config_path', return_value=config_path): - with patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager') as MockBackupManager: - # Create a real backup manager with custom backup dir - real_backup_manager = MCPHostConfigBackupManager(backup_root=backup_dir) - MockBackupManager.return_value = real_backup_manager - - # Write configuration (should create backup) - success = self.strategy.write_configuration(new_config, no_backup=False) - self.assertTrue(success) - - # Verify backup was created - backup_files = list(backup_dir.glob('codex/*.toml.*')) - self.assertGreater(len(backup_files), 0, "Backup file should be created") - - @regression_test - def test_write_configuration_skips_backup_when_requested(self): - """Test that write_configuration skips backup when no_backup=True.""" - with tempfile.TemporaryDirectory() as tmpdir: - config_path = Path(tmpdir) / "config.toml" - backup_dir = Path(tmpdir) / "backups" - - # Create initial config - initial_toml = """[mcp_servers.old-server] -command = "old-command" -""" - config_path.write_text(initial_toml) - - # Create new configuration - new_config = HostConfiguration(servers={ - 'new-server': MCPServerConfig( - command='new-command' - ) - }) - - # Patch paths - from unittest.mock import patch - with patch.object(self.strategy, 'get_config_path', return_value=config_path): - with patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager') as MockBackupManager: - real_backup_manager = MCPHostConfigBackupManager(backup_root=backup_dir) - MockBackupManager.return_value = real_backup_manager - - # Write configuration with no_backup=True - success = self.strategy.write_configuration(new_config, no_backup=True) - self.assertTrue(success) - - # Verify no backup was created - if backup_dir.exists(): - backup_files = list(backup_dir.glob('codex/*.toml.*')) - self.assertEqual(len(backup_files), 0, "No backup should be created when no_backup=True") - - @regression_test - def test_write_configuration_no_backup_for_new_file(self): - """Test that no backup is created when writing to a new file.""" - with tempfile.TemporaryDirectory() as tmpdir: - config_path = Path(tmpdir) / "config.toml" - backup_dir = Path(tmpdir) / "backups" - - # Don't create initial file - this is a new file - - # Create new configuration - new_config = HostConfiguration(servers={ - 'new-server': MCPServerConfig( - command='new-command' - ) - }) - - # Patch paths - from unittest.mock import patch - with patch.object(self.strategy, 'get_config_path', return_value=config_path): - with patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager') as MockBackupManager: - real_backup_manager = MCPHostConfigBackupManager(backup_root=backup_dir) - MockBackupManager.return_value = real_backup_manager - - # Write configuration to new file - success = self.strategy.write_configuration(new_config, no_backup=False) - self.assertTrue(success) - - # Verify file was created - self.assertTrue(config_path.exists()) - - # Verify no backup was created (nothing to backup) - if backup_dir.exists(): - backup_files = list(backup_dir.glob('codex/*.toml.*')) - self.assertEqual(len(backup_files), 0, "No backup for new file") - - @regression_test - def test_codex_hostname_supported_in_backup_system(self): - """Test that 'codex' hostname is supported by the backup system.""" - with tempfile.TemporaryDirectory() as tmpdir: - config_path = Path(tmpdir) / "config.toml" - backup_dir = Path(tmpdir) / "backups" - - # Create a config file - config_path.write_text("[mcp_servers.test]\ncommand = 'test'\n") - - # Create backup manager - backup_manager = MCPHostConfigBackupManager(backup_root=backup_dir) - - # Create backup with 'codex' hostname - should not raise validation error - result = backup_manager.create_backup(config_path, 'codex') - - # Verify backup succeeded - self.assertTrue(result.success, "Backup with 'codex' hostname should succeed") - self.assertIsNotNone(result.backup_path) - - # Verify backup filename follows pattern - backup_filename = result.backup_path.name - self.assertTrue(backup_filename.startswith('config.toml.codex.')) - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/regression/test_mcp_codex_host_strategy.py b/tests/regression/test_mcp_codex_host_strategy.py deleted file mode 100644 index c72a623..0000000 --- a/tests/regression/test_mcp_codex_host_strategy.py +++ /dev/null @@ -1,163 +0,0 @@ -""" -Codex MCP Host Strategy Tests - -Tests for CodexHostStrategy implementation including path resolution, -configuration read/write, TOML handling, and host detection. -""" - -import unittest -import tempfile -import tomllib -from unittest.mock import patch, mock_open, MagicMock -from pathlib import Path - -from wobble.decorators import regression_test - -from hatch.mcp_host_config.strategies import CodexHostStrategy -from hatch.mcp_host_config.models import MCPServerConfig, HostConfiguration - -# Import test data loader from local tests module -import sys -from pathlib import Path -sys.path.insert(0, str(Path(__file__).parent.parent)) -from test_data_utils import MCPHostConfigTestDataLoader - - -class TestCodexHostStrategy(unittest.TestCase): - """Test suite for CodexHostStrategy implementation.""" - - def setUp(self): - """Set up test environment.""" - self.strategy = CodexHostStrategy() - self.test_data_loader = MCPHostConfigTestDataLoader() - - @regression_test - def test_codex_config_path_resolution(self): - """Test Codex configuration path resolution.""" - config_path = self.strategy.get_config_path() - - # Verify path structure (use normalized path for cross-platform compatibility) - self.assertIsNotNone(config_path) - normalized_path = str(config_path).replace('\\', '/') - self.assertTrue(normalized_path.endswith('.codex/config.toml')) - self.assertEqual(config_path.name, 'config.toml') - self.assertEqual(config_path.suffix, '.toml') # Verify TOML extension - - @regression_test - def test_codex_config_key(self): - """Test Codex configuration key.""" - config_key = self.strategy.get_config_key() - # Codex uses underscore, not camelCase - self.assertEqual(config_key, "mcp_servers") - self.assertNotEqual(config_key, "mcpServers") # Verify different from other hosts - - @regression_test - def test_codex_server_config_validation_stdio(self): - """Test Codex STDIO server configuration validation.""" - # Test local server validation - local_config = MCPServerConfig( - command="npx", - args=["-y", "package"] - ) - self.assertTrue(self.strategy.validate_server_config(local_config)) - - @regression_test - def test_codex_server_config_validation_http(self): - """Test Codex HTTP server configuration validation.""" - # Test remote server validation - remote_config = MCPServerConfig( - url="https://api.example.com/mcp" - ) - self.assertTrue(self.strategy.validate_server_config(remote_config)) - - @patch('pathlib.Path.exists') - @regression_test - def test_codex_host_availability_detection(self, mock_exists): - """Test Codex host availability detection.""" - # Test when Codex directory exists - mock_exists.return_value = True - self.assertTrue(self.strategy.is_host_available()) - - # Test when Codex directory doesn't exist - mock_exists.return_value = False - self.assertFalse(self.strategy.is_host_available()) - - @regression_test - def test_codex_read_configuration_success(self): - """Test successful Codex TOML configuration reading.""" - # Load test data - test_toml_path = Path(__file__).parent.parent / "test_data" / "codex" / "valid_config.toml" - - with patch.object(self.strategy, 'get_config_path', return_value=test_toml_path): - config = self.strategy.read_configuration() - - # Verify configuration was read - self.assertIsInstance(config, HostConfiguration) - self.assertIn('context7', config.servers) - - # Verify server details - server = config.servers['context7'] - self.assertEqual(server.command, 'npx') - self.assertEqual(server.args, ['-y', '@upstash/context7-mcp']) - - # Verify nested env section was parsed correctly - self.assertIsNotNone(server.env) - self.assertEqual(server.env.get('MY_VAR'), 'value') - - @regression_test - def test_codex_read_configuration_file_not_exists(self): - """Test Codex configuration reading when file doesn't exist.""" - non_existent_path = Path("/non/existent/path/config.toml") - - with patch.object(self.strategy, 'get_config_path', return_value=non_existent_path): - config = self.strategy.read_configuration() - - # Should return empty configuration without error - self.assertIsInstance(config, HostConfiguration) - self.assertEqual(len(config.servers), 0) - - @regression_test - def test_codex_write_configuration_preserves_features(self): - """Test that write_configuration preserves [features] section.""" - with tempfile.TemporaryDirectory() as tmpdir: - config_path = Path(tmpdir) / "config.toml" - - # Create initial config with features section - initial_toml = """[features] -rmcp_client = true - -[mcp_servers.existing] -command = "old-command" -""" - config_path.write_text(initial_toml) - - # Create new configuration to write - new_config = HostConfiguration(servers={ - 'new-server': MCPServerConfig( - command='new-command', - args=['--test'] - ) - }) - - # Write configuration - with patch.object(self.strategy, 'get_config_path', return_value=config_path): - success = self.strategy.write_configuration(new_config, no_backup=True) - self.assertTrue(success) - - # Read back and verify features section preserved - with open(config_path, 'rb') as f: - result_data = tomllib.load(f) - - # Verify features section preserved - self.assertIn('features', result_data) - self.assertTrue(result_data['features'].get('rmcp_client')) - - # Verify new server added - self.assertIn('mcp_servers', result_data) - self.assertIn('new-server', result_data['mcp_servers']) - self.assertEqual(result_data['mcp_servers']['new-server']['command'], 'new-command') - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/regression/test_mcp_codex_model_validation.py b/tests/regression/test_mcp_codex_model_validation.py deleted file mode 100644 index b952f70..0000000 --- a/tests/regression/test_mcp_codex_model_validation.py +++ /dev/null @@ -1,117 +0,0 @@ -""" -Codex MCP Model Validation Tests - -Tests for MCPServerConfigCodex model validation including Codex-specific fields, -Omni conversion, and registry integration. -""" - -import unittest -from wobble.decorators import regression_test - -from hatch.mcp_host_config.models import ( - MCPServerConfigCodex, MCPServerConfigOmni, MCPHostType, HOST_MODEL_REGISTRY -) - - -class TestCodexModelValidation(unittest.TestCase): - """Test suite for Codex model validation.""" - - @regression_test - def test_codex_specific_fields_accepted(self): - """Test that Codex-specific fields are accepted in MCPServerConfigCodex.""" - # Create model with Codex-specific fields - config = MCPServerConfigCodex( - command="npx", - args=["-y", "package"], - env={"API_KEY": "test"}, - # Codex-specific fields - env_vars=["PATH", "HOME"], - cwd="/workspace", - startup_timeout_sec=10, - tool_timeout_sec=60, - enabled=True, - enabled_tools=["read", "write"], - disabled_tools=["delete"], - bearer_token_env_var="AUTH_TOKEN", - http_headers={"X-Custom": "value"}, - env_http_headers={"X-Auth": "AUTH_VAR"} - ) - - # Verify all fields are accessible - self.assertEqual(config.command, "npx") - self.assertEqual(config.env_vars, ["PATH", "HOME"]) - self.assertEqual(config.cwd, "/workspace") - self.assertEqual(config.startup_timeout_sec, 10) - self.assertEqual(config.tool_timeout_sec, 60) - self.assertTrue(config.enabled) - self.assertEqual(config.enabled_tools, ["read", "write"]) - self.assertEqual(config.disabled_tools, ["delete"]) - self.assertEqual(config.bearer_token_env_var, "AUTH_TOKEN") - self.assertEqual(config.http_headers, {"X-Custom": "value"}) - self.assertEqual(config.env_http_headers, {"X-Auth": "AUTH_VAR"}) - - @regression_test - def test_codex_from_omni_conversion(self): - """Test MCPServerConfigCodex.from_omni() conversion.""" - # Create Omni model with Codex-specific fields - omni = MCPServerConfigOmni( - command="npx", - args=["-y", "package"], - env={"API_KEY": "test"}, - # Codex-specific fields - env_vars=["PATH"], - startup_timeout_sec=15, - tool_timeout_sec=90, - enabled=True, - enabled_tools=["read"], - disabled_tools=["write"], - bearer_token_env_var="TOKEN", - headers={"X-Test": "value"}, # Universal field (maps to http_headers in Codex) - env_http_headers={"X-Env": "VAR"}, - # Non-Codex fields (should be excluded) - envFile="/path/to/env", # VS Code specific - disabled=True # Kiro specific - ) - - # Convert to Codex model - codex = MCPServerConfigCodex.from_omni(omni) - - # Verify Codex fields transferred correctly - self.assertEqual(codex.command, "npx") - self.assertEqual(codex.env_vars, ["PATH"]) - self.assertEqual(codex.startup_timeout_sec, 15) - self.assertEqual(codex.tool_timeout_sec, 90) - self.assertTrue(codex.enabled) - self.assertEqual(codex.enabled_tools, ["read"]) - self.assertEqual(codex.disabled_tools, ["write"]) - self.assertEqual(codex.bearer_token_env_var, "TOKEN") - self.assertEqual(codex.http_headers, {"X-Test": "value"}) - self.assertEqual(codex.env_http_headers, {"X-Env": "VAR"}) - - # Verify non-Codex fields excluded (should not have these attributes) - with self.assertRaises(AttributeError): - _ = codex.envFile - with self.assertRaises(AttributeError): - _ = codex.disabled - - @regression_test - def test_host_model_registry_contains_codex(self): - """Test that HOST_MODEL_REGISTRY contains Codex model.""" - # Verify CODEX is in registry - self.assertIn(MCPHostType.CODEX, HOST_MODEL_REGISTRY) - - # Verify it maps to correct model class - self.assertEqual( - HOST_MODEL_REGISTRY[MCPHostType.CODEX], - MCPServerConfigCodex - ) - - # Verify we can instantiate from registry - model_class = HOST_MODEL_REGISTRY[MCPHostType.CODEX] - instance = model_class(command="test") - self.assertIsInstance(instance, MCPServerConfigCodex) - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/regression/test_mcp_kiro_backup_integration.py b/tests/regression/test_mcp_kiro_backup_integration.py deleted file mode 100644 index 72b8d79..0000000 --- a/tests/regression/test_mcp_kiro_backup_integration.py +++ /dev/null @@ -1,241 +0,0 @@ -"""Tests for Kiro MCP backup integration. - -This module tests the integration between KiroHostStrategy and the backup system, -ensuring that Kiro configurations are properly backed up during write operations. -""" - -import json -import tempfile -import unittest -from pathlib import Path -from unittest.mock import patch, MagicMock - -from wobble.decorators import regression_test - -from hatch.mcp_host_config.strategies import KiroHostStrategy -from hatch.mcp_host_config.models import HostConfiguration, MCPServerConfig -from hatch.mcp_host_config.backup import MCPHostConfigBackupManager, BackupResult - - -class TestKiroBackupIntegration(unittest.TestCase): - """Test Kiro backup integration with host strategy.""" - - def setUp(self): - """Set up test environment.""" - self.temp_dir = Path(tempfile.mkdtemp(prefix="test_kiro_backup_")) - self.config_dir = self.temp_dir / ".kiro" / "settings" - self.config_dir.mkdir(parents=True) - self.config_file = self.config_dir / "mcp.json" - - self.backup_dir = self.temp_dir / "backups" - self.backup_manager = MCPHostConfigBackupManager(backup_root=self.backup_dir) - - self.strategy = KiroHostStrategy() - - def tearDown(self): - """Clean up test environment.""" - import shutil - shutil.rmtree(self.temp_dir, ignore_errors=True) - - @regression_test - def test_write_configuration_creates_backup_by_default(self): - """Test that write_configuration creates backup by default when file exists.""" - # Create initial configuration - initial_config = { - "mcpServers": { - "existing-server": { - "command": "uvx", - "args": ["existing-package"] - } - }, - "otherSettings": { - "theme": "dark" - } - } - - with open(self.config_file, 'w') as f: - json.dump(initial_config, f, indent=2) - - # Create new configuration to write - server_config = MCPServerConfig( - command="uvx", - args=["new-package"] - ) - host_config = HostConfiguration(servers={"new-server": server_config}) - - # Mock the strategy's get_config_path to return our test file - # Mock the backup manager creation to use our test backup manager - with patch.object(self.strategy, 'get_config_path', return_value=self.config_file), \ - patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager', return_value=self.backup_manager): - # Write configuration (should create backup) - result = self.strategy.write_configuration(host_config, no_backup=False) - - # Verify write succeeded - self.assertTrue(result) - - # Verify backup was created - backups = self.backup_manager.list_backups("kiro") - self.assertEqual(len(backups), 1) - - # Verify backup contains original content - backup_content = json.loads(backups[0].file_path.read_text()) - self.assertEqual(backup_content, initial_config) - - # Verify new configuration was written - new_content = json.loads(self.config_file.read_text()) - self.assertIn("new-server", new_content["mcpServers"]) - self.assertEqual(new_content["otherSettings"], {"theme": "dark"}) # Preserved - - @regression_test - def test_write_configuration_skips_backup_when_requested(self): - """Test that write_configuration skips backup when no_backup=True.""" - # Create initial configuration - initial_config = { - "mcpServers": { - "existing-server": { - "command": "uvx", - "args": ["existing-package"] - } - } - } - - with open(self.config_file, 'w') as f: - json.dump(initial_config, f, indent=2) - - # Create new configuration to write - server_config = MCPServerConfig( - command="uvx", - args=["new-package"] - ) - host_config = HostConfiguration(servers={"new-server": server_config}) - - # Mock the strategy's get_config_path to return our test file - # Mock the backup manager creation to use our test backup manager - with patch.object(self.strategy, 'get_config_path', return_value=self.config_file), \ - patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager', return_value=self.backup_manager): - # Write configuration with no_backup=True - result = self.strategy.write_configuration(host_config, no_backup=True) - - # Verify write succeeded - self.assertTrue(result) - - # Verify no backup was created - backups = self.backup_manager.list_backups("kiro") - self.assertEqual(len(backups), 0) - - # Verify new configuration was written - new_content = json.loads(self.config_file.read_text()) - self.assertIn("new-server", new_content["mcpServers"]) - - @regression_test - def test_write_configuration_no_backup_for_new_file(self): - """Test that no backup is created when writing to a new file.""" - # Ensure config file doesn't exist - self.assertFalse(self.config_file.exists()) - - # Create configuration to write - server_config = MCPServerConfig( - command="uvx", - args=["new-package"] - ) - host_config = HostConfiguration(servers={"new-server": server_config}) - - # Mock the strategy's get_config_path to return our test file - # Mock the backup manager creation to use our test backup manager - with patch.object(self.strategy, 'get_config_path', return_value=self.config_file), \ - patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager', return_value=self.backup_manager): - # Write configuration - result = self.strategy.write_configuration(host_config, no_backup=False) - - # Verify write succeeded - self.assertTrue(result) - - # Verify no backup was created (file didn't exist) - backups = self.backup_manager.list_backups("kiro") - self.assertEqual(len(backups), 0) - - # Verify configuration was written - self.assertTrue(self.config_file.exists()) - new_content = json.loads(self.config_file.read_text()) - self.assertIn("new-server", new_content["mcpServers"]) - - @regression_test - def test_backup_failure_prevents_write(self): - """Test that backup failure prevents configuration write.""" - # Create initial configuration - initial_config = { - "mcpServers": { - "existing-server": { - "command": "uvx", - "args": ["existing-package"] - } - } - } - - with open(self.config_file, 'w') as f: - json.dump(initial_config, f, indent=2) - - # Create new configuration to write - server_config = MCPServerConfig( - command="uvx", - args=["new-package"] - ) - host_config = HostConfiguration(servers={"new-server": server_config}) - - # Mock backup manager to fail - with patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager') as mock_backup_class: - mock_backup_manager = MagicMock() - mock_backup_manager.create_backup.return_value = BackupResult( - success=False, - error_message="Backup failed" - ) - mock_backup_class.return_value = mock_backup_manager - - # Mock the strategy's get_config_path to return our test file - with patch.object(self.strategy, 'get_config_path', return_value=self.config_file): - # Write configuration (should fail due to backup failure) - result = self.strategy.write_configuration(host_config, no_backup=False) - - # Verify write failed - self.assertFalse(result) - - # Verify original configuration is unchanged - current_content = json.loads(self.config_file.read_text()) - self.assertEqual(current_content, initial_config) - - @regression_test - def test_kiro_hostname_supported_in_backup_system(self): - """Test that 'kiro' hostname is supported by the backup system.""" - # Create test configuration file - test_config = { - "mcpServers": { - "test-server": { - "command": "uvx", - "args": ["test-package"] - } - } - } - - with open(self.config_file, 'w') as f: - json.dump(test_config, f, indent=2) - - # Test backup creation with 'kiro' hostname - result = self.backup_manager.create_backup(self.config_file, "kiro") - - # Verify backup succeeded - self.assertTrue(result.success) - self.assertIsNotNone(result.backup_path) - self.assertTrue(result.backup_path.exists()) - - # Verify backup filename format - expected_pattern = r"mcp\.json\.kiro\.\d{8}_\d{6}_\d{6}" - import re - self.assertRegex(result.backup_path.name, expected_pattern) - - # Verify backup content - backup_content = json.loads(result.backup_path.read_text()) - self.assertEqual(backup_content, test_config) - - -if __name__ == '__main__': - unittest.main() \ No newline at end of file diff --git a/tests/regression/test_mcp_kiro_cli_integration.py b/tests/regression/test_mcp_kiro_cli_integration.py deleted file mode 100644 index 575f16a..0000000 --- a/tests/regression/test_mcp_kiro_cli_integration.py +++ /dev/null @@ -1,141 +0,0 @@ -""" -Kiro MCP CLI Integration Tests - -Tests for CLI argument parsing and integration with Kiro-specific arguments. -""" - -import unittest -from unittest.mock import patch, MagicMock - -from wobble.decorators import regression_test - -from hatch.cli_hatch import handle_mcp_configure - - -class TestKiroCLIIntegration(unittest.TestCase): - """Test suite for Kiro CLI argument integration.""" - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @regression_test - def test_kiro_cli_with_disabled_flag(self, mock_manager_class): - """Test CLI with --disabled flag for Kiro.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='kiro', - server_name='test-server', - command='auggie', - args=['--mcp'], - disabled=True, # Kiro-specific argument - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify configure_server was called with Kiro model - mock_manager.configure_server.assert_called_once() - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - - # Verify Kiro-specific field was set - self.assertTrue(server_config.disabled) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @regression_test - def test_kiro_cli_with_auto_approve_tools(self, mock_manager_class): - """Test CLI with --auto-approve-tools for Kiro.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='kiro', - server_name='test-server', - command='auggie', - args=['--mcp'], # Required parameter - auto_approve_tools=['codebase-retrieval', 'fetch'], - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify autoApprove field was set correctly - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertEqual(len(server_config.autoApprove), 2) - self.assertIn('codebase-retrieval', server_config.autoApprove) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @regression_test - def test_kiro_cli_with_disable_tools(self, mock_manager_class): - """Test CLI with --disable-tools for Kiro.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='kiro', - server_name='test-server', - command='python', - args=['server.py'], # Required parameter - disable_tools=['dangerous-tool', 'risky-tool'], - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify disabledTools field was set correctly - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertEqual(len(server_config.disabledTools), 2) - self.assertIn('dangerous-tool', server_config.disabledTools) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @regression_test - def test_kiro_cli_combined_arguments(self, mock_manager_class): - """Test CLI with multiple Kiro-specific arguments combined.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='kiro', - server_name='comprehensive-server', - command='auggie', - args=['--mcp', '-m', 'default'], - disabled=False, - auto_approve_tools=['codebase-retrieval'], - disable_tools=['dangerous-tool'], - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify all Kiro fields were set correctly - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - - self.assertFalse(server_config.disabled) - self.assertEqual(len(server_config.autoApprove), 1) - self.assertEqual(len(server_config.disabledTools), 1) - self.assertIn('codebase-retrieval', server_config.autoApprove) - self.assertIn('dangerous-tool', server_config.disabledTools) - - -if __name__ == '__main__': - unittest.main() \ No newline at end of file diff --git a/tests/regression/test_mcp_kiro_decorator_registration.py b/tests/regression/test_mcp_kiro_decorator_registration.py deleted file mode 100644 index e6e4d06..0000000 --- a/tests/regression/test_mcp_kiro_decorator_registration.py +++ /dev/null @@ -1,71 +0,0 @@ -""" -Kiro MCP Decorator Registration Tests - -Tests for automatic strategy registration via @register_host_strategy decorator. -""" - -import unittest - -from wobble.decorators import regression_test - -from hatch.mcp_host_config.host_management import MCPHostRegistry -from hatch.mcp_host_config.models import MCPHostType - - -class TestKiroDecoratorRegistration(unittest.TestCase): - """Test suite for Kiro decorator registration.""" - - @regression_test - def test_kiro_strategy_registration(self): - """Test that KiroHostStrategy is properly registered.""" - # Import strategies to trigger registration - import hatch.mcp_host_config.strategies - - # Verify Kiro is registered - self.assertIn(MCPHostType.KIRO, MCPHostRegistry._strategies) - - # Verify correct strategy class - strategy_class = MCPHostRegistry._strategies[MCPHostType.KIRO] - self.assertEqual(strategy_class.__name__, "KiroHostStrategy") - - @regression_test - def test_kiro_strategy_instantiation(self): - """Test that Kiro strategy can be instantiated.""" - # Import strategies to trigger registration - import hatch.mcp_host_config.strategies - - strategy = MCPHostRegistry.get_strategy(MCPHostType.KIRO) - - # Verify strategy instance - self.assertIsNotNone(strategy) - self.assertEqual(strategy.__class__.__name__, "KiroHostStrategy") - - @regression_test - def test_kiro_in_host_detection(self): - """Test that Kiro appears in host detection.""" - # Import strategies to trigger registration - import hatch.mcp_host_config.strategies - - # Get all registered host types - registered_hosts = list(MCPHostRegistry._strategies.keys()) - - # Verify Kiro is included - self.assertIn(MCPHostType.KIRO, registered_hosts) - - @regression_test - def test_kiro_registry_consistency(self): - """Test that Kiro registration is consistent across calls.""" - # Import strategies to trigger registration - import hatch.mcp_host_config.strategies - - # Get strategy multiple times - strategy1 = MCPHostRegistry.get_strategy(MCPHostType.KIRO) - strategy2 = MCPHostRegistry.get_strategy(MCPHostType.KIRO) - - # Verify same class (not necessarily same instance) - self.assertEqual(strategy1.__class__, strategy2.__class__) - self.assertEqual(strategy1.__class__.__name__, "KiroHostStrategy") - - -if __name__ == '__main__': - unittest.main() \ No newline at end of file diff --git a/tests/regression/test_mcp_kiro_host_strategy.py b/tests/regression/test_mcp_kiro_host_strategy.py deleted file mode 100644 index 00afc66..0000000 --- a/tests/regression/test_mcp_kiro_host_strategy.py +++ /dev/null @@ -1,214 +0,0 @@ -""" -Kiro MCP Host Strategy Tests - -Tests for KiroHostStrategy implementation including path resolution, -configuration read/write, and host detection. -""" - -import unittest -import json -from unittest.mock import patch, mock_open, MagicMock -from pathlib import Path - -from wobble.decorators import regression_test - -from hatch.mcp_host_config.strategies import KiroHostStrategy -from hatch.mcp_host_config.models import MCPServerConfig, HostConfiguration - -# Import test data loader from local tests module -import sys -from pathlib import Path -sys.path.insert(0, str(Path(__file__).parent.parent)) -from test_data_utils import MCPHostConfigTestDataLoader - - -class TestKiroHostStrategy(unittest.TestCase): - """Test suite for KiroHostStrategy implementation.""" - - def setUp(self): - """Set up test environment.""" - self.strategy = KiroHostStrategy() - self.test_data_loader = MCPHostConfigTestDataLoader() - - @regression_test - def test_kiro_config_path_resolution(self): - """Test Kiro configuration path resolution.""" - config_path = self.strategy.get_config_path() - - # Verify path structure (use normalized path for cross-platform compatibility) - self.assertIsNotNone(config_path) - normalized_path = str(config_path).replace('\\', '/') - self.assertTrue(normalized_path.endswith('.kiro/settings/mcp.json')) - self.assertEqual(config_path.name, 'mcp.json') - - @regression_test - def test_kiro_config_key(self): - """Test Kiro configuration key.""" - config_key = self.strategy.get_config_key() - self.assertEqual(config_key, "mcpServers") - - @regression_test - def test_kiro_server_config_validation(self): - """Test Kiro server configuration validation.""" - # Test local server validation - local_config = MCPServerConfig( - command="auggie", - args=["--mcp"] - ) - self.assertTrue(self.strategy.validate_server_config(local_config)) - - # Test remote server validation - remote_config = MCPServerConfig( - url="https://api.example.com/mcp" - ) - self.assertTrue(self.strategy.validate_server_config(remote_config)) - - # Test invalid configuration (should raise ValidationError during creation) - with self.assertRaises(Exception): # Pydantic ValidationError - invalid_config = MCPServerConfig() - self.strategy.validate_server_config(invalid_config) - - @patch('pathlib.Path.exists') - @regression_test - def test_kiro_host_availability_detection(self, mock_exists): - """Test Kiro host availability detection.""" - # Test when Kiro directory exists - mock_exists.return_value = True - self.assertTrue(self.strategy.is_host_available()) - - # Test when Kiro directory doesn't exist - mock_exists.return_value = False - self.assertFalse(self.strategy.is_host_available()) - - @patch('builtins.open', new_callable=mock_open) - @patch('pathlib.Path.exists') - @patch('json.load') - @regression_test - def test_kiro_read_configuration_success(self, mock_json_load, mock_exists, mock_file): - """Test successful Kiro configuration reading.""" - # Mock file exists and JSON content - mock_exists.return_value = True - mock_json_load.return_value = { - "mcpServers": { - "augment": { - "command": "auggie", - "args": ["--mcp", "-m", "default"], - "autoApprove": ["codebase-retrieval"] - } - } - } - - config = self.strategy.read_configuration() - - # Verify configuration structure - self.assertIsInstance(config, HostConfiguration) - self.assertIn("augment", config.servers) - - server = config.servers["augment"] - self.assertEqual(server.command, "auggie") - self.assertEqual(len(server.args), 3) - - @patch('pathlib.Path.exists') - @regression_test - def test_kiro_read_configuration_file_not_exists(self, mock_exists): - """Test Kiro configuration reading when file doesn't exist.""" - mock_exists.return_value = False - - config = self.strategy.read_configuration() - - # Should return empty configuration - self.assertIsInstance(config, HostConfiguration) - self.assertEqual(len(config.servers), 0) - - @patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager') - @patch('hatch.mcp_host_config.strategies.AtomicFileOperations') - @patch('builtins.open', new_callable=mock_open) - @patch('pathlib.Path.exists') - @patch('pathlib.Path.mkdir') - @patch('json.load') - @regression_test - def test_kiro_write_configuration_success(self, mock_json_load, mock_mkdir, - mock_exists, mock_file, mock_atomic_ops_class, mock_backup_manager_class): - """Test successful Kiro configuration writing.""" - # Mock existing file with other settings - mock_exists.return_value = True - mock_json_load.return_value = { - "otherSettings": {"theme": "dark"}, - "mcpServers": {} - } - - # Mock backup and atomic operations - mock_backup_manager = MagicMock() - mock_backup_manager_class.return_value = mock_backup_manager - - mock_atomic_ops = MagicMock() - mock_atomic_ops_class.return_value = mock_atomic_ops - - # Create test configuration - server_config = MCPServerConfig( - command="auggie", - args=["--mcp"] - ) - config = HostConfiguration(servers={"test-server": server_config}) - - result = self.strategy.write_configuration(config) - - # Verify success - self.assertTrue(result) - - # Verify atomic write was called - mock_atomic_ops.atomic_write_with_backup.assert_called_once() - - # Verify configuration structure in the call - call_args = mock_atomic_ops.atomic_write_with_backup.call_args - written_data = call_args[1]['data'] # keyword argument 'data' - self.assertIn("otherSettings", written_data) # Preserved - self.assertIn("mcpServers", written_data) # Updated - self.assertIn("test-server", written_data["mcpServers"]) - - @patch('hatch.mcp_host_config.strategies.MCPHostConfigBackupManager') - @patch('hatch.mcp_host_config.strategies.AtomicFileOperations') - @patch('builtins.open', new_callable=mock_open) - @patch('pathlib.Path.exists') - @patch('pathlib.Path.mkdir') - @regression_test - def test_kiro_write_configuration_new_file(self, mock_mkdir, mock_exists, - mock_file, mock_atomic_ops_class, mock_backup_manager_class): - """Test Kiro configuration writing when file doesn't exist.""" - # Mock file doesn't exist - mock_exists.return_value = False - - # Mock backup and atomic operations - mock_backup_manager = MagicMock() - mock_backup_manager_class.return_value = mock_backup_manager - - mock_atomic_ops = MagicMock() - mock_atomic_ops_class.return_value = mock_atomic_ops - - # Create test configuration - server_config = MCPServerConfig( - command="auggie", - args=["--mcp"] - ) - config = HostConfiguration(servers={"new-server": server_config}) - - result = self.strategy.write_configuration(config) - - # Verify success - self.assertTrue(result) - - # Verify directory creation was attempted - mock_mkdir.assert_called_once() - - # Verify atomic write was called - mock_atomic_ops.atomic_write_with_backup.assert_called_once() - - # Verify configuration structure - call_args = mock_atomic_ops.atomic_write_with_backup.call_args - written_data = call_args[1]['data'] # keyword argument 'data' - self.assertIn("mcpServers", written_data) - self.assertIn("new-server", written_data["mcpServers"]) - - -if __name__ == '__main__': - unittest.main() \ No newline at end of file diff --git a/tests/regression/test_mcp_kiro_model_validation.py b/tests/regression/test_mcp_kiro_model_validation.py deleted file mode 100644 index 2e8ea05..0000000 --- a/tests/regression/test_mcp_kiro_model_validation.py +++ /dev/null @@ -1,116 +0,0 @@ -""" -Kiro MCP Model Validation Tests - -Tests for MCPServerConfigKiro Pydantic model behavior, field validation, -and Kiro-specific field combinations. -""" - -import unittest -from typing import Optional, List - -from wobble.decorators import regression_test - -from hatch.mcp_host_config.models import ( - MCPServerConfigKiro, - MCPServerConfigOmni, - MCPHostType -) - - -class TestMCPServerConfigKiro(unittest.TestCase): - """Test suite for MCPServerConfigKiro model validation.""" - - @regression_test - def test_kiro_model_with_disabled_field(self): - """Test Kiro model with disabled field.""" - config = MCPServerConfigKiro( - name="kiro-server", - command="auggie", - args=["--mcp", "-m", "default"], - disabled=True - ) - - self.assertEqual(config.command, "auggie") - self.assertTrue(config.disabled) - self.assertEqual(config.type, "stdio") # Inferred - - @regression_test - def test_kiro_model_with_auto_approve_tools(self): - """Test Kiro model with autoApprove field.""" - config = MCPServerConfigKiro( - name="kiro-server", - command="auggie", - autoApprove=["codebase-retrieval", "fetch"] - ) - - self.assertEqual(config.command, "auggie") - self.assertEqual(len(config.autoApprove), 2) - self.assertIn("codebase-retrieval", config.autoApprove) - self.assertIn("fetch", config.autoApprove) - - @regression_test - def test_kiro_model_with_disabled_tools(self): - """Test Kiro model with disabledTools field.""" - config = MCPServerConfigKiro( - name="kiro-server", - command="python", - disabledTools=["dangerous-tool", "risky-tool"] - ) - - self.assertEqual(config.command, "python") - self.assertEqual(len(config.disabledTools), 2) - self.assertIn("dangerous-tool", config.disabledTools) - - @regression_test - def test_kiro_model_all_fields_combined(self): - """Test Kiro model with all Kiro-specific fields.""" - config = MCPServerConfigKiro( - name="kiro-server", - command="auggie", - args=["--mcp"], - env={"DEBUG": "true"}, - disabled=False, - autoApprove=["codebase-retrieval"], - disabledTools=["dangerous-tool"] - ) - - # Verify all fields - self.assertEqual(config.command, "auggie") - self.assertFalse(config.disabled) - self.assertEqual(len(config.autoApprove), 1) - self.assertEqual(len(config.disabledTools), 1) - self.assertEqual(config.env["DEBUG"], "true") - - @regression_test - def test_kiro_model_minimal_configuration(self): - """Test Kiro model with minimal configuration.""" - config = MCPServerConfigKiro( - name="kiro-server", - command="auggie" - ) - - self.assertEqual(config.command, "auggie") - self.assertEqual(config.type, "stdio") # Inferred - self.assertIsNone(config.disabled) - self.assertIsNone(config.autoApprove) - self.assertIsNone(config.disabledTools) - - @regression_test - def test_kiro_model_remote_server_with_kiro_fields(self): - """Test Kiro model with remote server and Kiro-specific fields.""" - config = MCPServerConfigKiro( - name="kiro-remote", - url="https://api.example.com/mcp", - headers={"Authorization": "Bearer token"}, - disabled=True, - autoApprove=["safe-tool"] - ) - - self.assertEqual(config.url, "https://api.example.com/mcp") - self.assertTrue(config.disabled) - self.assertEqual(len(config.autoApprove), 1) - self.assertEqual(config.type, "sse") # Inferred for remote - - -if __name__ == '__main__': - unittest.main() \ No newline at end of file diff --git a/tests/regression/test_mcp_kiro_omni_conversion.py b/tests/regression/test_mcp_kiro_omni_conversion.py deleted file mode 100644 index 8c223ec..0000000 --- a/tests/regression/test_mcp_kiro_omni_conversion.py +++ /dev/null @@ -1,104 +0,0 @@ -""" -Kiro MCP Omni Conversion Tests - -Tests for conversion from MCPServerConfigOmni to MCPServerConfigKiro -using the from_omni() method. -""" - -import unittest - -from wobble.decorators import regression_test - -from hatch.mcp_host_config.models import ( - MCPServerConfigKiro, - MCPServerConfigOmni -) - - -class TestKiroFromOmniConversion(unittest.TestCase): - """Test suite for Kiro from_omni() conversion method.""" - - @regression_test - def test_kiro_from_omni_with_supported_fields(self): - """Test Kiro from_omni with supported fields.""" - omni = MCPServerConfigOmni( - name="kiro-server", - command="auggie", - args=["--mcp", "-m", "default"], - disabled=True, - autoApprove=["codebase-retrieval", "fetch"], - disabledTools=["dangerous-tool"] - ) - - # Convert to Kiro model - kiro = MCPServerConfigKiro.from_omni(omni) - - # Verify all supported fields transferred - self.assertEqual(kiro.name, "kiro-server") - self.assertEqual(kiro.command, "auggie") - self.assertEqual(len(kiro.args), 3) - self.assertTrue(kiro.disabled) - self.assertEqual(len(kiro.autoApprove), 2) - self.assertEqual(len(kiro.disabledTools), 1) - - @regression_test - def test_kiro_from_omni_with_unsupported_fields(self): - """Test Kiro from_omni excludes unsupported fields.""" - omni = MCPServerConfigOmni( - name="kiro-server", - command="python", - disabled=True, # Kiro field - envFile=".env", # VS Code field (unsupported by Kiro) - timeout=30000 # Gemini field (unsupported by Kiro) - ) - - # Convert to Kiro model - kiro = MCPServerConfigKiro.from_omni(omni) - - # Verify Kiro fields transferred - self.assertEqual(kiro.command, "python") - self.assertTrue(kiro.disabled) - - # Verify unsupported fields NOT transferred - self.assertFalse(hasattr(kiro, 'envFile') and kiro.envFile is not None) - self.assertFalse(hasattr(kiro, 'timeout') and kiro.timeout is not None) - - @regression_test - def test_kiro_from_omni_exclude_unset_behavior(self): - """Test that from_omni respects exclude_unset=True.""" - omni = MCPServerConfigOmni( - name="kiro-server", - command="auggie" - # disabled, autoApprove, disabledTools not set - ) - - kiro = MCPServerConfigKiro.from_omni(omni) - - # Verify unset fields remain None - self.assertIsNone(kiro.disabled) - self.assertIsNone(kiro.autoApprove) - self.assertIsNone(kiro.disabledTools) - - @regression_test - def test_kiro_from_omni_remote_server_conversion(self): - """Test Kiro from_omni with remote server configuration.""" - omni = MCPServerConfigOmni( - name="kiro-remote", - url="https://api.example.com/mcp", - headers={"Authorization": "Bearer token"}, - disabled=False, - autoApprove=["safe-tool"] - ) - - kiro = MCPServerConfigKiro.from_omni(omni) - - # Verify remote server fields - self.assertEqual(kiro.url, "https://api.example.com/mcp") - self.assertEqual(kiro.headers["Authorization"], "Bearer token") - self.assertFalse(kiro.disabled) - self.assertEqual(len(kiro.autoApprove), 1) - self.assertEqual(kiro.type, "sse") # Inferred for remote - - -if __name__ == '__main__': - unittest.main() \ No newline at end of file diff --git a/tests/run_environment_tests.py b/tests/run_environment_tests.py index e38e219..eb0b7a0 100644 --- a/tests/run_environment_tests.py +++ b/tests/run_environment_tests.py @@ -7,118 +7,174 @@ # Configure logging logging.basicConfig( level=logging.INFO, - format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', + format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", handlers=[ logging.StreamHandler(), - logging.FileHandler("environment_test_results.log") - ] + logging.FileHandler("environment_test_results.log"), + ], ) logger = logging.getLogger("hatch.test_runner") if __name__ == "__main__": # Add parent directory to path for imports sys.path.insert(0, str(Path(__file__).parent.parent)) - + # Discover and run tests test_loader = unittest.TestLoader() if len(sys.argv) > 1 and sys.argv[1] == "--env-only": # Run only environment tests logger.info("Running environment tests only...") - test_suite = test_loader.loadTestsFromName("test_env_manip.PackageEnvironmentTests") + test_suite = test_loader.loadTestsFromName( + "test_env_manip.PackageEnvironmentTests" + ) elif len(sys.argv) > 1 and sys.argv[1] == "--remote-only": # Run only remote integration tests logger.info("Running remote integration tests only...") - test_suite = test_loader.loadTestsFromName("test_registry_retriever.RegistryRetrieverTests") - test_suite = test_loader.loadTestsFromName("test_online_package_loader.OnlinePackageLoaderTests") + test_suite = test_loader.loadTestsFromName( + "test_registry_retriever.RegistryRetrieverTests" + ) + test_suite = test_loader.loadTestsFromName( + "test_online_package_loader.OnlinePackageLoaderTests" + ) elif len(sys.argv) > 1 and sys.argv[1] == "--registry-online": # Run only registry online mode tests logger.info("Running registry retriever online mode tests...") - test_suite = test_loader.loadTestsFromName("test_registry_retriever.RegistryRetrieverTests") + test_suite = test_loader.loadTestsFromName( + "test_registry_retriever.RegistryRetrieverTests" + ) elif len(sys.argv) > 1 and sys.argv[1] == "--package-online": # Run only package loader online mode tests logger.info("Running package loader online mode tests...") - test_suite = test_loader.loadTestsFromName("test_online_package_loader.OnlinePackageLoaderTests") + test_suite = test_loader.loadTestsFromName( + "test_online_package_loader.OnlinePackageLoaderTests" + ) elif len(sys.argv) > 1 and sys.argv[1] == "--installer-only": # Run only installer interface tests logger.info("Running installer interface tests only...") - test_suite = test_loader.loadTestsFromName("test_installer_base.BaseInstallerTests") + test_suite = test_loader.loadTestsFromName( + "test_installer_base.BaseInstallerTests" + ) elif len(sys.argv) > 1 and sys.argv[1] == "--hatch-installer-only": # Run only HatchInstaller tests logger.info("Running HatchInstaller tests only...") - test_suite = test_loader.loadTestsFromName("test_hatch_installer.TestHatchInstaller") + test_suite = test_loader.loadTestsFromName( + "test_hatch_installer.TestHatchInstaller" + ) elif len(sys.argv) > 1 and sys.argv[1] == "--python-installer-only": # Run only PythonInstaller tests logger.info("Running PythonInstaller tests only...") - test_mocking = test_loader.loadTestsFromName("test_python_installer.TestPythonInstaller") - test_integration = test_loader.loadTestsFromName("test_python_installer.TestPythonInstallerIntegration") + test_mocking = test_loader.loadTestsFromName( + "test_python_installer.TestPythonInstaller" + ) + test_integration = test_loader.loadTestsFromName( + "test_python_installer.TestPythonInstallerIntegration" + ) test_suite = unittest.TestSuite([test_mocking, test_integration]) elif len(sys.argv) > 1 and sys.argv[1] == "--python-env-manager-only": # Run only PythonEnvironmentManager tests (mocked) logger.info("Running PythonEnvironmentManager mocked tests only...") - test_suite = test_loader.loadTestsFromName("test_python_environment_manager.TestPythonEnvironmentManager") + test_suite = test_loader.loadTestsFromName( + "test_python_environment_manager.TestPythonEnvironmentManager" + ) elif len(sys.argv) > 1 and sys.argv[1] == "--python-env-manager-integration": # Run only PythonEnvironmentManager integration tests (requires conda/mamba) logger.info("Running PythonEnvironmentManager integration tests only...") - test_integration = test_loader.loadTestsFromName("test_python_environment_manager.TestPythonEnvironmentManagerIntegration") - test_enhanced = test_loader.loadTestsFromName("test_python_environment_manager.TestPythonEnvironmentManagerEnhancedFeatures") + test_integration = test_loader.loadTestsFromName( + "test_python_environment_manager.TestPythonEnvironmentManagerIntegration" + ) + test_enhanced = test_loader.loadTestsFromName( + "test_python_environment_manager.TestPythonEnvironmentManagerEnhancedFeatures" + ) test_suite = unittest.TestSuite([test_integration, test_enhanced]) elif len(sys.argv) > 1 and sys.argv[1] == "--python-env-manager-all": # Run all PythonEnvironmentManager tests logger.info("Running all PythonEnvironmentManager tests...") - test_mocked = test_loader.loadTestsFromName("test_python_environment_manager.TestPythonEnvironmentManager") - test_integration = test_loader.loadTestsFromName("test_python_environment_manager.TestPythonEnvironmentManagerIntegration") - test_enhanced = test_loader.loadTestsFromName("test_python_environment_manager.TestPythonEnvironmentManagerEnhancedFeatures") + test_mocked = test_loader.loadTestsFromName( + "test_python_environment_manager.TestPythonEnvironmentManager" + ) + test_integration = test_loader.loadTestsFromName( + "test_python_environment_manager.TestPythonEnvironmentManagerIntegration" + ) + test_enhanced = test_loader.loadTestsFromName( + "test_python_environment_manager.TestPythonEnvironmentManagerEnhancedFeatures" + ) test_suite = unittest.TestSuite([test_mocked, test_integration, test_enhanced]) elif len(sys.argv) > 1 and sys.argv[1] == "--system-installer-only": # Run only SystemInstaller tests logger.info("Running SystemInstaller tests only...") - test_mocking = test_loader.loadTestsFromName("test_system_installer.TestSystemInstaller") - test_integration = test_loader.loadTestsFromName("test_system_installer.TestSystemInstallerIntegration") + test_mocking = test_loader.loadTestsFromName( + "test_system_installer.TestSystemInstaller" + ) + test_integration = test_loader.loadTestsFromName( + "test_system_installer.TestSystemInstallerIntegration" + ) test_suite = unittest.TestSuite([test_mocking, test_integration]) elif len(sys.argv) > 1 and sys.argv[1] == "--docker-installer-only": # Run only DockerInstaller tests logger.info("Running DockerInstaller tests only...") - test_mocking = test_loader.loadTestsFromName("test_docker_installer.TestDockerInstaller") - test_integration = test_loader.loadTestsFromName("test_docker_installer.TestDockerInstallerIntegration") + test_mocking = test_loader.loadTestsFromName( + "test_docker_installer.TestDockerInstaller" + ) + test_integration = test_loader.loadTestsFromName( + "test_docker_installer.TestDockerInstallerIntegration" + ) test_suite = unittest.TestSuite([test_mocking, test_integration]) elif len(sys.argv) > 1 and sys.argv[1] == "--all-installers": # Run all installer tests logger.info("Running all installer tests...") - hatch_tests = test_loader.loadTestsFromName("test_hatch_installer.TestHatchInstaller") - python_tests_mocking = test_loader.loadTestsFromName("test_python_installer.TestPythonInstaller") - python_tests_integration = test_loader.loadTestsFromName("test_python_installer.TestPythonInstallerIntegration") - system_tests = test_loader.loadTestsFromName("test_system_installer.TestSystemInstaller") - system_tests_integration = test_loader.loadTestsFromName("test_system_installer.TestSystemInstallerIntegration") - docker_tests = test_loader.loadTestsFromName("test_docker_installer.TestDockerInstaller") - docker_tests_integration = test_loader.loadTestsFromName("test_docker_installer.TestDockerInstallerIntegration") + hatch_tests = test_loader.loadTestsFromName( + "test_hatch_installer.TestHatchInstaller" + ) + python_tests_mocking = test_loader.loadTestsFromName( + "test_python_installer.TestPythonInstaller" + ) + python_tests_integration = test_loader.loadTestsFromName( + "test_python_installer.TestPythonInstallerIntegration" + ) + system_tests = test_loader.loadTestsFromName( + "test_system_installer.TestSystemInstaller" + ) + system_tests_integration = test_loader.loadTestsFromName( + "test_system_installer.TestSystemInstallerIntegration" + ) + docker_tests = test_loader.loadTestsFromName( + "test_docker_installer.TestDockerInstaller" + ) + docker_tests_integration = test_loader.loadTestsFromName( + "test_docker_installer.TestDockerInstallerIntegration" + ) - test_suite = unittest.TestSuite([ - hatch_tests, - python_tests_mocking, - python_tests_integration, - system_tests, - system_tests_integration, - docker_tests, - docker_tests_integration - ]) + test_suite = unittest.TestSuite( + [ + hatch_tests, + python_tests_mocking, + python_tests_integration, + system_tests, + system_tests_integration, + docker_tests, + docker_tests_integration, + ] + ) elif len(sys.argv) > 1 and sys.argv[1] == "--registry-only": # Run only installer registry tests logger.info("Running installer registry tests only...") - test_suite = test_loader.loadTestsFromName("test_registry.TestInstallerRegistry") + test_suite = test_loader.loadTestsFromName( + "test_registry.TestInstallerRegistry" + ) else: # Run all tests logger.info("Running all package environment tests...") - test_suite = test_loader.discover('.', pattern='test_*.py') + test_suite = test_loader.discover(".", pattern="test_*.py") # Run the tests test_runner = unittest.TextTestRunner(verbosity=2) result = test_runner.run(test_suite) - + # Log test results summary logger.info(f"Tests run: {result.testsRun}") logger.info(f"Errors: {len(result.errors)}") logger.info(f"Failures: {len(result.failures)}") - + # Exit with appropriate status code sys.exit(not result.wasSuccessful()) diff --git a/tests/test_cli_version.py b/tests/test_cli_version.py index 43d4361..bd35921 100644 --- a/tests/test_cli_version.py +++ b/tests/test_cli_version.py @@ -17,10 +17,12 @@ from unittest.mock import patch, MagicMock from io import StringIO -# Add parent directory to path +# Add parent directory to path for test imports sys.path.insert(0, str(Path(__file__).parent.parent)) -from hatch.cli_hatch import main, get_hatch_version +# Import after path setup (required for test environment) +from hatch.cli_hatch import main # noqa: E402 +from hatch.cli.cli_utils import get_hatch_version # noqa: E402 try: from wobble.decorators import regression_test, integration_test @@ -28,95 +30,104 @@ # Fallback decorators if wobble not available def regression_test(func): return func - + def integration_test(scope="component"): def decorator(func): return func + return decorator class TestVersionCommand(unittest.TestCase): """Test suite for hatch --version command implementation.""" - + @regression_test def test_get_hatch_version_retrieves_from_metadata(self): """Test get_hatch_version() retrieves version from importlib.metadata.""" - with patch('hatch.cli_hatch.version', return_value='0.7.0-dev.3') as mock_version: + with patch( + "hatch.cli.cli_utils.version", return_value="0.7.0-dev.3" + ) as mock_version: result = get_hatch_version() - self.assertEqual(result, '0.7.0-dev.3') - mock_version.assert_called_once_with('hatch') + self.assertEqual(result, "0.7.0-dev.3") + mock_version.assert_called_once_with("hatch-xclam") @regression_test def test_get_hatch_version_handles_package_not_found(self): """Test get_hatch_version() handles PackageNotFoundError gracefully.""" from importlib.metadata import PackageNotFoundError - with patch('hatch.cli_hatch.version', side_effect=PackageNotFoundError()): + with patch("hatch.cli.cli_utils.version", side_effect=PackageNotFoundError()): result = get_hatch_version() - self.assertEqual(result, 'unknown (development mode)') - + self.assertEqual(result, "unknown (development mode)") + @integration_test(scope="component") def test_version_command_displays_correct_format(self): """Test version command displays correct format via CLI.""" - test_args = ['hatch', '--version'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.get_hatch_version', return_value='0.7.0-dev.3'): - with patch('sys.stdout', new_callable=StringIO) as mock_stdout: + test_args = ["hatch", "--version"] + + with patch("sys.argv", test_args): + # Patch at point of use in __main__ (imported from cli_utils) + with patch( + "hatch.cli.__main__.get_hatch_version", return_value="0.7.0-dev.3" + ): + with patch("sys.stdout", new_callable=StringIO) as mock_stdout: with self.assertRaises(SystemExit) as cm: main() - + # argparse action='version' exits with code 0 self.assertEqual(cm.exception.code, 0) - + # Verify output format: "hatch 0.7.0-dev.3" output = mock_stdout.getvalue().strip() - self.assertRegex(output, r'hatch\s+0\.7\.0-dev\.3') - + self.assertRegex(output, r"hatch\s+0\.7\.0-dev\.3") + @integration_test(scope="component") def test_import_hatch_without_version_attribute(self): """Test that importing hatch module works without __version__ attribute.""" try: import hatch - + # Import should succeed self.assertIsNotNone(hatch) - + # __version__ should not exist (removed in implementation) - self.assertFalse(hasattr(hatch, '__version__'), - "hatch.__version__ should not exist after cleanup") - + self.assertFalse( + hasattr(hatch, "__version__"), + "hatch.__version__ should not exist after cleanup", + ) + except ImportError as e: self.fail(f"Failed to import hatch module: {e}") - + @regression_test def test_no_conflict_with_package_version_flag(self): """Test that --version (Hatch) doesn't conflict with -v (package version).""" # Test package add command with -v flag (package version specification) - test_args = ['hatch', 'package', 'add', 'test-package', '-v', '1.0.0'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env: + test_args = ["hatch", "package", "add", "test-package", "-v", "1.0.0"] + + with patch("sys.argv", test_args): + with patch("hatch.environment_manager.HatchEnvironmentManager") as mock_env: mock_env_instance = MagicMock() mock_env.return_value = mock_env_instance mock_env_instance.add_package_to_environment.return_value = True - + try: main() except SystemExit as e: # Should execute successfully (exit code 0) self.assertEqual(e.code, 0) - + # Verify package add was called with version argument mock_env_instance.add_package_to_environment.assert_called_once() call_args = mock_env_instance.add_package_to_environment.call_args - + # Version argument should be '1.0.0' - self.assertEqual(call_args[0][2], '1.0.0') # Third positional arg is version + self.assertEqual( + call_args[0][2], "1.0.0" + ) # Third positional arg is version -if __name__ == '__main__': +if __name__ == "__main__": unittest.main() - diff --git a/tests/test_data/codex/http_server.toml b/tests/test_data/codex/http_server.toml index 4a960da..c30f09f 100644 --- a/tests/test_data/codex/http_server.toml +++ b/tests/test_data/codex/http_server.toml @@ -4,4 +4,3 @@ bearer_token_env_var = "FIGMA_OAUTH_TOKEN" [mcp_servers.figma.http_headers] "X-Figma-Region" = "us-east-1" - diff --git a/tests/test_data/codex/stdio_server.toml b/tests/test_data/codex/stdio_server.toml index cb6c985..3ef5237 100644 --- a/tests/test_data/codex/stdio_server.toml +++ b/tests/test_data/codex/stdio_server.toml @@ -4,4 +4,3 @@ args = ["server.js"] [mcp_servers.test-server.env] API_KEY = "test-key" - diff --git a/tests/test_data/codex/valid_config.toml b/tests/test_data/codex/valid_config.toml index f464ef5..0340f8d 100644 --- a/tests/test_data/codex/valid_config.toml +++ b/tests/test_data/codex/valid_config.toml @@ -10,4 +10,3 @@ enabled = true [mcp_servers.context7.env] MY_VAR = "value" - diff --git a/tests/test_data/configs/mcp_backup_test_configs/complex_server.json b/tests/test_data/configs/mcp_backup_test_configs/complex_server.json index b501990..02d1621 100644 --- a/tests/test_data/configs/mcp_backup_test_configs/complex_server.json +++ b/tests/test_data/configs/mcp_backup_test_configs/complex_server.json @@ -22,4 +22,4 @@ } } } -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_backup_test_configs/simple_server.json b/tests/test_data/configs/mcp_backup_test_configs/simple_server.json index 99eb8d3..97539c9 100644 --- a/tests/test_data/configs/mcp_backup_test_configs/simple_server.json +++ b/tests/test_data/configs/mcp_backup_test_configs/simple_server.json @@ -7,4 +7,4 @@ ] } } -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/claude_desktop_config.json b/tests/test_data/configs/mcp_host_test_configs/claude_desktop_config.json index 6106744..da39e4f 100644 --- a/tests/test_data/configs/mcp_host_test_configs/claude_desktop_config.json +++ b/tests/test_data/configs/mcp_host_test_configs/claude_desktop_config.json @@ -1,4 +1,3 @@ { "mcpServers": {} } - diff --git a/tests/test_data/configs/mcp_host_test_configs/claude_desktop_config_with_server.json b/tests/test_data/configs/mcp_host_test_configs/claude_desktop_config_with_server.json index 39f52d2..869579a 100644 --- a/tests/test_data/configs/mcp_host_test_configs/claude_desktop_config_with_server.json +++ b/tests/test_data/configs/mcp_host_test_configs/claude_desktop_config_with_server.json @@ -9,4 +9,3 @@ } } } - diff --git a/tests/test_data/configs/mcp_host_test_configs/cursor_mcp.json b/tests/test_data/configs/mcp_host_test_configs/cursor_mcp.json index 6106744..da39e4f 100644 --- a/tests/test_data/configs/mcp_host_test_configs/cursor_mcp.json +++ b/tests/test_data/configs/mcp_host_test_configs/cursor_mcp.json @@ -1,4 +1,3 @@ { "mcpServers": {} } - diff --git a/tests/test_data/configs/mcp_host_test_configs/cursor_mcp_with_server.json b/tests/test_data/configs/mcp_host_test_configs/cursor_mcp_with_server.json index 4eac728..d948ab9 100644 --- a/tests/test_data/configs/mcp_host_test_configs/cursor_mcp_with_server.json +++ b/tests/test_data/configs/mcp_host_test_configs/cursor_mcp_with_server.json @@ -9,4 +9,3 @@ } } } - diff --git a/tests/test_data/configs/mcp_host_test_configs/environment_v2_multi_host.json b/tests/test_data/configs/mcp_host_test_configs/environment_v2_multi_host.json index f5170a5..a4860d1 100644 --- a/tests/test_data/configs/mcp_host_test_configs/environment_v2_multi_host.json +++ b/tests/test_data/configs/mcp_host_test_configs/environment_v2_multi_host.json @@ -41,4 +41,4 @@ } } ] -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/environment_v2_simple.json b/tests/test_data/configs/mcp_host_test_configs/environment_v2_simple.json index cdda403..d41e710 100644 --- a/tests/test_data/configs/mcp_host_test_configs/environment_v2_simple.json +++ b/tests/test_data/configs/mcp_host_test_configs/environment_v2_simple.json @@ -27,4 +27,4 @@ } } ] -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/gemini_cli_config.json b/tests/test_data/configs/mcp_host_test_configs/gemini_cli_config.json index 6106744..da39e4f 100644 --- a/tests/test_data/configs/mcp_host_test_configs/gemini_cli_config.json +++ b/tests/test_data/configs/mcp_host_test_configs/gemini_cli_config.json @@ -1,4 +1,3 @@ { "mcpServers": {} } - diff --git a/tests/test_data/configs/mcp_host_test_configs/gemini_cli_config_with_server.json b/tests/test_data/configs/mcp_host_test_configs/gemini_cli_config_with_server.json index c553c14..b092128 100644 --- a/tests/test_data/configs/mcp_host_test_configs/gemini_cli_config_with_server.json +++ b/tests/test_data/configs/mcp_host_test_configs/gemini_cli_config_with_server.json @@ -12,4 +12,3 @@ } } } - diff --git a/tests/test_data/configs/mcp_host_test_configs/kiro_mcp.json b/tests/test_data/configs/mcp_host_test_configs/kiro_mcp.json index 7001130..da39e4f 100644 --- a/tests/test_data/configs/mcp_host_test_configs/kiro_mcp.json +++ b/tests/test_data/configs/mcp_host_test_configs/kiro_mcp.json @@ -1,3 +1,3 @@ { "mcpServers": {} -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_complex.json b/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_complex.json index 485523e..c33cb43 100644 --- a/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_complex.json +++ b/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_complex.json @@ -19,4 +19,4 @@ "theme": "dark", "fontSize": 14 } -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_empty.json b/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_empty.json index 7001130..da39e4f 100644 --- a/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_empty.json +++ b/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_empty.json @@ -1,3 +1,3 @@ { "mcpServers": {} -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_with_server.json b/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_with_server.json index 3fbd102..abc5772 100644 --- a/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_with_server.json +++ b/tests/test_data/configs/mcp_host_test_configs/kiro_mcp_with_server.json @@ -11,4 +11,4 @@ "disabledTools": ["dangerous-tool"] } } -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/kiro_simple.json b/tests/test_data/configs/mcp_host_test_configs/kiro_simple.json index 8d8a263..0840832 100644 --- a/tests/test_data/configs/mcp_host_test_configs/kiro_simple.json +++ b/tests/test_data/configs/mcp_host_test_configs/kiro_simple.json @@ -11,4 +11,4 @@ ] } } -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/mcp_server_local.json b/tests/test_data/configs/mcp_host_test_configs/mcp_server_local.json index c78efce..8880682 100644 --- a/tests/test_data/configs/mcp_host_test_configs/mcp_server_local.json +++ b/tests/test_data/configs/mcp_host_test_configs/mcp_server_local.json @@ -9,4 +9,4 @@ "API_KEY": "test", "DEBUG": "true" } -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/mcp_server_local_minimal.json b/tests/test_data/configs/mcp_host_test_configs/mcp_server_local_minimal.json index 0ac4fa0..4378b82 100644 --- a/tests/test_data/configs/mcp_host_test_configs/mcp_server_local_minimal.json +++ b/tests/test_data/configs/mcp_host_test_configs/mcp_server_local_minimal.json @@ -3,4 +3,4 @@ "args": [ "minimal_server.py" ] -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/mcp_server_remote.json b/tests/test_data/configs/mcp_host_test_configs/mcp_server_remote.json index 637b58f..475ca3f 100644 --- a/tests/test_data/configs/mcp_host_test_configs/mcp_server_remote.json +++ b/tests/test_data/configs/mcp_host_test_configs/mcp_server_remote.json @@ -4,4 +4,4 @@ "Authorization": "Bearer token", "Content-Type": "application/json" } -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/mcp_server_remote_minimal.json b/tests/test_data/configs/mcp_host_test_configs/mcp_server_remote_minimal.json index cd3569c..1e7de81 100644 --- a/tests/test_data/configs/mcp_host_test_configs/mcp_server_remote_minimal.json +++ b/tests/test_data/configs/mcp_host_test_configs/mcp_server_remote_minimal.json @@ -1,3 +1,3 @@ { "url": "https://minimal.example.com/mcp" -} \ No newline at end of file +} diff --git a/tests/test_data/configs/mcp_host_test_configs/vscode_mcp.json b/tests/test_data/configs/mcp_host_test_configs/vscode_mcp.json index 6106744..da39e4f 100644 --- a/tests/test_data/configs/mcp_host_test_configs/vscode_mcp.json +++ b/tests/test_data/configs/mcp_host_test_configs/vscode_mcp.json @@ -1,4 +1,3 @@ { "mcpServers": {} } - diff --git a/tests/test_data/configs/mcp_host_test_configs/vscode_mcp_with_server.json b/tests/test_data/configs/mcp_host_test_configs/vscode_mcp_with_server.json index ff8de11..b8060d4 100644 --- a/tests/test_data/configs/mcp_host_test_configs/vscode_mcp_with_server.json +++ b/tests/test_data/configs/mcp_host_test_configs/vscode_mcp_with_server.json @@ -10,4 +10,3 @@ } } } - diff --git a/tests/test_data/fixtures/cli_reporter_fixtures.py b/tests/test_data/fixtures/cli_reporter_fixtures.py new file mode 100644 index 0000000..d46f505 --- /dev/null +++ b/tests/test_data/fixtures/cli_reporter_fixtures.py @@ -0,0 +1,153 @@ +"""Test fixtures for ResultReporter and ConversionReport integration tests. + +This module provides reusable ConversionReport and FieldOperation samples +for testing the CLI reporter infrastructure. Fixtures are defined as Python +objects for type safety and IDE support. + +Reference: R05 Β§4.2 (05-test_definition_v0.md) + +Fixture Categories: + - Single field operation samples (one per operation type) + - ConversionReport samples (various scenarios) + +Usage: + from tests.test_data.fixtures.cli_reporter_fixtures import ( + REPORT_MIXED_OPERATIONS, + FIELD_OP_UPDATED, + ) + + def test_all_fields_mapped_no_data_loss(self): + reporter = ResultReporter("test") + reporter.add_from_conversion_report(REPORT_MIXED_OPERATIONS) + assert len(reporter.consequences[0].children) == 4 +""" + +from hatch.mcp_host_config.reporting import ConversionReport, FieldOperation +from hatch.mcp_host_config.models import MCPHostType + +# ============================================================================= +# Single Field Operation Samples (one per operation type) +# ============================================================================= + +FIELD_OP_UPDATED = FieldOperation( + field_name="command", operation="UPDATED", old_value=None, new_value="python" +) +"""Field operation: UPDATED - field value changed from None to 'python'.""" + +FIELD_OP_UPDATED_WITH_OLD = FieldOperation( + field_name="command", operation="UPDATED", old_value="node", new_value="python" +) +"""Field operation: UPDATED - field value changed from 'node' to 'python'.""" + +FIELD_OP_UNSUPPORTED = FieldOperation( + field_name="timeout", operation="UNSUPPORTED", new_value=30 +) +"""Field operation: UNSUPPORTED - field not supported by target host.""" + +FIELD_OP_UNCHANGED = FieldOperation( + field_name="env", operation="UNCHANGED", new_value={} +) +"""Field operation: UNCHANGED - field value remained the same.""" + + +# ============================================================================= +# ConversionReport Samples +# ============================================================================= + +REPORT_SINGLE_UPDATE = ConversionReport( + operation="create", + server_name="test-server", + target_host=MCPHostType.CLAUDE_DESKTOP, + field_operations=[FIELD_OP_UPDATED], +) +"""ConversionReport: Single field update (create operation).""" + +REPORT_MIXED_OPERATIONS = ConversionReport( + operation="update", + server_name="weather-server", + target_host=MCPHostType.CURSOR, + field_operations=[ + FieldOperation( + field_name="command", + operation="UPDATED", + old_value="node", + new_value="python", + ), + FieldOperation( + field_name="args", + operation="UPDATED", + old_value=[], + new_value=["server.py"], + ), + FieldOperation( + field_name="env", operation="UNCHANGED", new_value={"API_KEY": "***"} + ), + FieldOperation(field_name="timeout", operation="UNSUPPORTED", new_value=60), + ], +) +"""ConversionReport: Mixed field operations (update operation). + +Contains: +- 2 UPDATED fields (command, args) +- 1 UNCHANGED field (env) +- 1 UNSUPPORTED field (timeout) +""" + +REPORT_EMPTY_FIELDS = ConversionReport( + operation="create", + server_name="minimal-server", + target_host=MCPHostType.VSCODE, + field_operations=[], +) +"""ConversionReport: Empty field operations list (edge case).""" + +REPORT_ALL_UNSUPPORTED = ConversionReport( + operation="migrate", + server_name="legacy-server", + source_host=MCPHostType.CLAUDE_DESKTOP, + target_host=MCPHostType.KIRO, + field_operations=[ + FieldOperation(field_name="trust", operation="UNSUPPORTED", new_value=True), + FieldOperation(field_name="cwd", operation="UNSUPPORTED", new_value="/app"), + ], +) +"""ConversionReport: All fields unsupported (migrate operation).""" + +REPORT_ALL_UNCHANGED = ConversionReport( + operation="update", + server_name="stable-server", + target_host=MCPHostType.CLAUDE_DESKTOP, + field_operations=[ + FieldOperation(field_name="command", operation="UNCHANGED", new_value="python"), + FieldOperation( + field_name="args", operation="UNCHANGED", new_value=["server.py"] + ), + ], +) +"""ConversionReport: All fields unchanged (no-op update).""" + +REPORT_DRY_RUN = ConversionReport( + operation="create", + server_name="preview-server", + target_host=MCPHostType.CURSOR, + field_operations=[ + FieldOperation( + field_name="command", + operation="UPDATED", + old_value=None, + new_value="python", + ), + ], + dry_run=True, +) +"""ConversionReport: Dry-run mode enabled.""" + +REPORT_WITH_ERROR = ConversionReport( + operation="create", + server_name="failed-server", + target_host=MCPHostType.VSCODE, + success=False, + error_message="Configuration file not found", + field_operations=[], +) +"""ConversionReport: Failed operation with error message.""" diff --git a/tests/test_data/fixtures/environment_host_configs.json b/tests/test_data/fixtures/environment_host_configs.json index 6877896..6f71192 100644 --- a/tests/test_data/fixtures/environment_host_configs.json +++ b/tests/test_data/fixtures/environment_host_configs.json @@ -31,7 +31,7 @@ } }, { - "name": "team-utilities", + "name": "team-utilities", "configured_hosts": { "claude-desktop": { "config_path": "~/.claude/config.json", diff --git a/tests/test_data/fixtures/host_sync_scenarios.json b/tests/test_data/fixtures/host_sync_scenarios.json index ef1f250..2c19dd8 100644 --- a/tests/test_data/fixtures/host_sync_scenarios.json +++ b/tests/test_data/fixtures/host_sync_scenarios.json @@ -23,7 +23,7 @@ "after": { "packages": [ { - "name": "weather-toolkit", + "name": "weather-toolkit", "configured_hosts": { "claude-desktop": { "config_path": "~/.claude/config.json", diff --git a/tests/test_data/mcp_adapters/__init__.py b/tests/test_data/mcp_adapters/__init__.py new file mode 100644 index 0000000..a1cbf60 --- /dev/null +++ b/tests/test_data/mcp_adapters/__init__.py @@ -0,0 +1,7 @@ +"""MCP adapter test data and infrastructure. + +This package provides data-driven test infrastructure for MCP adapter testing: +- canonical_configs.json: Canonical config values for all hosts +- host_registry.py: HostRegistry and HostSpec for metadata derivation +- assertions.py: Property-based assertion library +""" diff --git a/tests/test_data/mcp_adapters/assertions.py b/tests/test_data/mcp_adapters/assertions.py new file mode 100644 index 0000000..cf9df4b --- /dev/null +++ b/tests/test_data/mcp_adapters/assertions.py @@ -0,0 +1,142 @@ +"""Property-based assertion library for MCP adapter testing. + +All assertions verify adapter contracts using fields.py as the reference +through HostSpec metadata. No hardcoded field names β€” everything is derived. + +Usage: + >>> from tests.test_data.mcp_adapters.assertions import assert_only_supported_fields + >>> assert_only_supported_fields(result, host_spec) +""" + +from typing import Any, Dict + +from hatch.mcp_host_config.fields import EXCLUDED_ALWAYS + +# Import locally to avoid circular; HostSpec is used as type hint only +from tests.test_data.mcp_adapters.host_registry import HostSpec + + +def assert_only_supported_fields(result: Dict[str, Any], host: HostSpec) -> None: + """Verify result contains only fields from fields.py for this host. + + After field mapping, the result may contain host-native names (e.g., + Codex 'arguments' instead of 'args'). We account for this by also + accepting mapped field names. + + Args: + result: Serialized adapter output + host: HostSpec with metadata derived from fields.py + """ + result_fields = set(result.keys()) + # Build the set of allowed field names: supported + mapped target names + allowed = set(host.supported_fields) + for _universal, host_specific in host.field_mappings.items(): + allowed.add(host_specific) + + unsupported = result_fields - allowed + assert not unsupported, ( + f"[{host.host_name}] Unsupported fields in result: {sorted(unsupported)}. " + f"Allowed: {sorted(allowed)}" + ) + + +def assert_excluded_fields_absent(result: Dict[str, Any], host: HostSpec) -> None: + """Verify EXCLUDED_ALWAYS fields are not in result. + + Args: + result: Serialized adapter output + host: HostSpec (used for error context) + """ + excluded_present = set(result.keys()) & EXCLUDED_ALWAYS + assert ( + not excluded_present + ), f"[{host.host_name}] Excluded fields found in result: {sorted(excluded_present)}" + + +def assert_transport_present(result: Dict[str, Any], host: HostSpec) -> None: + """Verify at least one transport field is present in result. + + Args: + result: Serialized adapter output + host: HostSpec with transport fields derived from fields.py + """ + transport_fields = host.get_transport_fields() + present = set(result.keys()) & transport_fields + assert present, ( + f"[{host.host_name}] No transport field present in result. " + f"Expected one of: {sorted(transport_fields)}" + ) + + +def assert_transport_mutual_exclusion(result: Dict[str, Any], host: HostSpec) -> None: + """Verify exactly one transport field is present in result. + + Args: + result: Serialized adapter output + host: HostSpec with transport fields derived from fields.py + """ + transport_fields = host.get_transport_fields() + present = set(result.keys()) & transport_fields + assert len(present) == 1, ( + f"[{host.host_name}] Expected exactly 1 transport, " + f"got {len(present)}: {sorted(present)}" + ) + + +def assert_field_mappings_applied(result: Dict[str, Any], host: HostSpec) -> None: + """Verify field mappings from fields.py were applied. + + For hosts with field mappings (e.g., Codex), universal field names + should NOT appear in the result β€” only the mapped names should. + + Args: + result: Serialized adapter output + host: HostSpec with field_mappings derived from fields.py + """ + for universal, host_specific in host.field_mappings.items(): + if universal in result: + assert False, ( + f"[{host.host_name}] Universal field '{universal}' should have been " + f"mapped to '{host_specific}'" + ) + + +def assert_tool_lists_coexist(result: Dict[str, Any], host: HostSpec) -> None: + """Verify both allowlist and denylist fields are present in result. + + Only meaningful for hosts that support tool lists. Skips silently + if the host has no tool list configuration. + + Args: + result: Serialized adapter output + host: HostSpec with tool list config derived from fields.py + """ + tool_config = host.get_tool_list_config() + if not tool_config: + return + + allowlist = tool_config["allowlist"] + denylist = tool_config["denylist"] + + assert ( + allowlist in result + ), f"[{host.host_name}] Allowlist field '{allowlist}' missing from result" + assert ( + denylist in result + ), f"[{host.host_name}] Denylist field '{denylist}' missing from result" + + +def assert_unsupported_field_absent( + result: Dict[str, Any], host: HostSpec, field_name: str +) -> None: + """Verify a specific unsupported field is not in result. + + Args: + result: Serialized adapter output + host: HostSpec (used for error context) + field_name: The unsupported field that should have been filtered + """ + assert field_name not in result, ( + f"[{host.host_name}] Unsupported field '{field_name}' should have been " + f"filtered but is present in result" + ) diff --git a/tests/test_data/mcp_adapters/canonical_configs.json b/tests/test_data/mcp_adapters/canonical_configs.json new file mode 100644 index 0000000..49bc2ac --- /dev/null +++ b/tests/test_data/mcp_adapters/canonical_configs.json @@ -0,0 +1,78 @@ +{ + "claude-desktop": { + "command": "python", + "args": ["-m", "mcp_server"], + "env": {"API_KEY": "test_key"}, + "url": null, + "headers": null, + "type": "stdio" + }, + "claude-code": { + "command": "python", + "args": ["-m", "mcp_server"], + "env": {"API_KEY": "test_key"}, + "url": null, + "headers": null, + "type": "stdio" + }, + "vscode": { + "command": "python", + "args": ["-m", "mcp_server"], + "env": {"API_KEY": "test_key"}, + "url": null, + "headers": null, + "type": "stdio", + "envFile": ".env", + "inputs": [{"id": "api-key", "type": "promptString", "description": "API Key"}] + }, + "cursor": { + "command": "python", + "args": ["-m", "mcp_server"], + "env": {"API_KEY": "test_key"}, + "url": null, + "headers": null, + "type": "stdio", + "envFile": ".env" + }, + "lmstudio": { + "command": "python", + "args": ["-m", "mcp_server"], + "env": {"API_KEY": "test_key"}, + "url": null, + "headers": null, + "type": "stdio" + }, + "gemini": { + "command": "python", + "args": ["-m", "mcp_server"], + "env": {"API_KEY": "test_key"}, + "url": null, + "headers": null, + "httpUrl": null, + "timeout": 30000, + "trust": false, + "cwd": "/app", + "includeTools": ["tool1", "tool2"], + "excludeTools": ["tool3"] + }, + "kiro": { + "command": "python", + "args": ["-m", "mcp_server"], + "env": {"API_KEY": "test_key"}, + "url": null, + "headers": null, + "disabled": false, + "autoApprove": ["tool1"], + "disabledTools": ["tool2"] + }, + "codex": { + "command": "python", + "arguments": ["-m", "mcp_server"], + "env": {"API_KEY": "test_key"}, + "url": null, + "http_headers": null, + "cwd": "/app", + "enabled_tools": ["tool1", "tool2"], + "disabled_tools": ["tool3"] + } +} diff --git a/tests/test_data/mcp_adapters/host_registry.py b/tests/test_data/mcp_adapters/host_registry.py new file mode 100644 index 0000000..34d6a49 --- /dev/null +++ b/tests/test_data/mcp_adapters/host_registry.py @@ -0,0 +1,367 @@ +"""Host registry for data-driven MCP adapter testing. + +This module provides the HostRegistry and HostSpec classes that bridge +minimal fixture data (canonical_configs.json) with complete host metadata +derived from fields.py (the single source of truth). + +Architecture: + - HostSpec: Complete host specification with metadata derived from fields.py + - HostRegistry: Discovery, loading, and test case generation + - Generator functions: Create parameterized test cases from registry data + +Design Principle: + fields.py is the ONLY source of metadata. Fixtures contain ONLY config values. + No metadata duplication. Changes to fields.py automatically reflected in tests. +""" + +import json +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any, Dict, FrozenSet, List, Optional, Set, Tuple + +from hatch.mcp_host_config.adapters.base import BaseAdapter +from hatch.mcp_host_config.adapters.claude import ClaudeAdapter +from hatch.mcp_host_config.adapters.codex import CodexAdapter +from hatch.mcp_host_config.adapters.cursor import CursorAdapter +from hatch.mcp_host_config.adapters.gemini import GeminiAdapter +from hatch.mcp_host_config.adapters.kiro import KiroAdapter +from hatch.mcp_host_config.adapters.lmstudio import LMStudioAdapter +from hatch.mcp_host_config.adapters.vscode import VSCodeAdapter +from hatch.mcp_host_config.fields import ( + CLAUDE_FIELDS, + CODEX_FIELD_MAPPINGS, + CODEX_FIELDS, + CURSOR_FIELDS, + EXCLUDED_ALWAYS, + GEMINI_FIELDS, + KIRO_FIELDS, + LMSTUDIO_FIELDS, + TYPE_SUPPORTING_HOSTS, + VSCODE_FIELDS, +) +from hatch.mcp_host_config.models import MCPServerConfig + + +# ============================================================================ +# Field set mapping: host name β†’ field set from fields.py +# ============================================================================ + +FIELD_SETS: Dict[str, FrozenSet[str]] = { + "claude-desktop": CLAUDE_FIELDS, + "claude-code": CLAUDE_FIELDS, + "vscode": VSCODE_FIELDS, + "cursor": CURSOR_FIELDS, + "lmstudio": LMSTUDIO_FIELDS, + "gemini": GEMINI_FIELDS, + "kiro": KIRO_FIELDS, + "codex": CODEX_FIELDS, +} + +# Reverse mappings for Codex (host-native name β†’ universal name) +CODEX_REVERSE_MAPPINGS: Dict[str, str] = {v: k for k, v in CODEX_FIELD_MAPPINGS.items()} + + +# ============================================================================ +# HostSpec dataclass +# ============================================================================ + + +@dataclass +class HostSpec: + """Complete host specification with metadata derived from fields.py. + + Attributes: + host_name: Host identifier (e.g., "claude-desktop", "gemini") + canonical_config: Raw config values from fixture (host-native field names) + supported_fields: Fields this host supports (from fields.py) + field_mappings: Universalβ†’host-specific field name mappings (from fields.py) + """ + + host_name: str + canonical_config: Dict[str, Any] + supported_fields: FrozenSet[str] = field(default_factory=frozenset) + field_mappings: Dict[str, str] = field(default_factory=dict) + + def get_adapter(self) -> BaseAdapter: + """Instantiate the adapter for this host.""" + adapter_map = { + "claude-desktop": lambda: ClaudeAdapter(variant="desktop"), + "claude-code": lambda: ClaudeAdapter(variant="code"), + "vscode": VSCodeAdapter, + "cursor": CursorAdapter, + "lmstudio": LMStudioAdapter, + "gemini": GeminiAdapter, + "kiro": KiroAdapter, + "codex": CodexAdapter, + } + factory = adapter_map[self.host_name] + return factory() + + def load_config(self) -> MCPServerConfig: + """Load canonical config as MCPServerConfig object. + + Handles reverse field mapping for hosts with non-standard names + (e.g., Codex 'arguments' β†’ 'args' for MCPServerConfig). + + Returns: + MCPServerConfig populated with canonical values (None values excluded) + """ + config_data = {} + for key, value in self.canonical_config.items(): + if value is None: + continue + # Reverse-map host-native names to MCPServerConfig field names + universal_key = CODEX_REVERSE_MAPPINGS.get(key, key) + config_data[universal_key] = value + + # Ensure name is set for MCPServerConfig + if "name" not in config_data: + config_data["name"] = f"test-{self.host_name}" + + return MCPServerConfig(**config_data) + + def get_transport_fields(self) -> Set[str]: + """Compute transport fields from supported_fields.""" + return self.supported_fields & {"command", "url", "httpUrl"} + + def supports_type_field(self) -> bool: + """Check if 'type' field is supported.""" + return self.host_name in TYPE_SUPPORTING_HOSTS + + def get_tool_list_config(self) -> Optional[Dict[str, str]]: + """Compute tool list configuration from supported_fields. + + Returns: + Dict with 'allowlist' and 'denylist' keys mapping to field names, + or None if host doesn't support tool lists. + """ + if ( + "includeTools" in self.supported_fields + and "excludeTools" in self.supported_fields + ): + return {"allowlist": "includeTools", "denylist": "excludeTools"} + if ( + "enabled_tools" in self.supported_fields + and "disabled_tools" in self.supported_fields + ): + return {"allowlist": "enabled_tools", "denylist": "disabled_tools"} + return None + + def compute_expected_fields(self, input_fields: Set[str]) -> Set[str]: + """Compute which fields should appear after filtering. + + Args: + input_fields: Set of field names in the input config + + Returns: + Set of field names expected in the serialized output + """ + return (input_fields & self.supported_fields) - EXCLUDED_ALWAYS + + def __repr__(self) -> str: + return f"HostSpec({self.host_name})" + + +# ============================================================================ +# Test case dataclasses +# ============================================================================ + + +@dataclass +class SyncTestCase: + """Test case for cross-host sync testing.""" + + from_host: HostSpec + to_host: HostSpec + test_id: str + + +@dataclass +class ValidationTestCase: + """Test case for validation property testing.""" + + host: HostSpec + property_name: str + test_id: str + + +@dataclass +class FilterTestCase: + """Test case for field filtering testing.""" + + host: HostSpec + unsupported_field: str + test_id: str + + +# ============================================================================ +# HostRegistry class +# ============================================================================ + + +class HostRegistry: + """Discovers hosts from fixtures and derives metadata from fields.py. + + The registry bridges minimal fixture data (canonical config values) with + complete host metadata derived from fields.py. This ensures fields.py + remains the single source of truth for all host specifications. + + Usage: + >>> registry = HostRegistry(Path("tests/test_data/mcp_adapters/canonical_configs.json")) + >>> hosts = registry.all_hosts() + >>> pairs = registry.all_pairs() + >>> codex = registry.get_host("codex") + """ + + def __init__(self, fixtures_path: Path): + """Load canonical configs and derive metadata from fields.py. + + Args: + fixtures_path: Path to canonical_configs.json + """ + with open(fixtures_path) as f: + raw_configs = json.load(f) + + self._hosts: Dict[str, HostSpec] = {} + for host_name, config in raw_configs.items(): + supported = FIELD_SETS.get(host_name) + if supported is None: + raise ValueError( + f"Host '{host_name}' in fixture has no field set in fields.py" + ) + + mappings: Dict[str, str] = {} + if host_name == "codex": + mappings = dict(CODEX_FIELD_MAPPINGS) + + self._hosts[host_name] = HostSpec( + host_name=host_name, + canonical_config=config, + supported_fields=supported, + field_mappings=mappings, + ) + + def all_hosts(self) -> List[HostSpec]: + """Return all discovered host specifications (sorted by name).""" + return sorted(self._hosts.values(), key=lambda h: h.host_name) + + def get_host(self, name: str) -> HostSpec: + """Get specific host by name. + + Args: + name: Host identifier (e.g., "claude-desktop", "gemini") + + Raises: + KeyError: If host not found in registry + """ + if name not in self._hosts: + available = ", ".join(sorted(self._hosts.keys())) + raise KeyError(f"Host '{name}' not found. Available: {available}") + return self._hosts[name] + + def all_pairs(self) -> List[Tuple[HostSpec, HostSpec]]: + """Generate all (from_host, to_host) combinations for O(nΒ²) testing.""" + hosts = self.all_hosts() + return [(from_h, to_h) for from_h in hosts for to_h in hosts] + + def hosts_supporting_field(self, field_name: str) -> List[HostSpec]: + """Find hosts that support a specific field. + + Args: + field_name: Field name to query (e.g., "httpUrl", "envFile") + """ + return [h for h in self.all_hosts() if field_name in h.supported_fields] + + def hosts_with_tool_lists(self) -> List[HostSpec]: + """Find hosts that support tool allowlist/denylist.""" + return [h for h in self.all_hosts() if h.get_tool_list_config() is not None] + + +# ============================================================================ +# Test case generator functions +# ============================================================================ + + +def generate_sync_test_cases(registry: HostRegistry) -> List[SyncTestCase]: + """Generate all cross-host sync test cases from registry. + + Returns one test case per (from_host, to_host) pair. + For 8 hosts: 8Γ—8 = 64 combinations. + """ + return [ + SyncTestCase( + from_host=from_h, + to_host=to_h, + test_id=f"sync_{from_h.host_name}_to_{to_h.host_name}", + ) + for from_h, to_h in registry.all_pairs() + ] + + +def generate_validation_test_cases( + registry: HostRegistry, +) -> List[ValidationTestCase]: + """Generate property-based validation test cases from fields.py metadata. + + Generates: + - tool_lists_coexist: For hosts with tool list support + - transport_mutual_exclusion: For all hosts + """ + cases: List[ValidationTestCase] = [] + + # Tool list coexistence: hosts with tool lists + for host in registry.hosts_with_tool_lists(): + cases.append( + ValidationTestCase( + host=host, + property_name="tool_lists_coexist", + test_id=f"{host.host_name}_tool_lists_coexist", + ) + ) + + # Transport mutual exclusion: all hosts + for host in registry.all_hosts(): + cases.append( + ValidationTestCase( + host=host, + property_name="transport_mutual_exclusion", + test_id=f"{host.host_name}_transport_mutual_exclusion", + ) + ) + + return cases + + +def generate_unsupported_field_test_cases( + registry: HostRegistry, +) -> List[FilterTestCase]: + """Generate unsupported field filtering test cases from fields.py. + + For each host, computes the set of fields it does NOT support + (from the union of all host field sets) and generates a test case + for each unsupported field. + """ + # Compute all possible MCP fields from fields.py + all_possible_fields = ( + CLAUDE_FIELDS + | VSCODE_FIELDS + | CURSOR_FIELDS + | LMSTUDIO_FIELDS + | GEMINI_FIELDS + | KIRO_FIELDS + | CODEX_FIELDS + ) + + cases: List[FilterTestCase] = [] + for host in registry.all_hosts(): + unsupported = all_possible_fields - host.supported_fields + for field_name in sorted(unsupported): + cases.append( + FilterTestCase( + host=host, + unsupported_field=field_name, + test_id=f"{host.host_name}_filters_{field_name}", + ) + ) + + return cases diff --git a/tests/test_data/packages/basic/base_pkg/hatch_mcp_server.py b/tests/test_data/packages/basic/base_pkg/hatch_mcp_server.py index 49800db..d232a69 100644 --- a/tests/test_data/packages/basic/base_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/basic/base_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for base_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting base_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/basic/base_pkg/hatch_metadata.json b/tests/test_data/packages/basic/base_pkg/hatch_metadata.json index 1a37107..0748471 100644 --- a/tests/test_data/packages/basic/base_pkg/hatch_metadata.json +++ b/tests/test_data/packages/basic/base_pkg/hatch_metadata.json @@ -26,4 +26,4 @@ "description": "Example tool for base_pkg" } ] -} \ No newline at end of file +} diff --git a/tests/test_data/packages/basic/base_pkg/mcp_server.py b/tests/test_data/packages/basic/base_pkg/mcp_server.py index d827370..c6876e0 100644 --- a/tests/test_data/packages/basic/base_pkg/mcp_server.py +++ b/tests/test_data/packages/basic/base_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for base_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("base_pkg", log_level="WARNING") + @mcp.tool() def base_pkg_tool(param: str) -> str: """Example tool function for base_pkg. @@ -17,5 +19,6 @@ def base_pkg_tool(param: str) -> str: """ return f"Processed by base_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/basic/base_pkg_v2/hatch_mcp_server.py b/tests/test_data/packages/basic/base_pkg_v2/hatch_mcp_server.py index 38a76c0..c09b5ae 100644 --- a/tests/test_data/packages/basic/base_pkg_v2/hatch_mcp_server.py +++ b/tests/test_data/packages/basic/base_pkg_v2/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for base_pkg_v2. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting base_pkg_v2 via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/basic/base_pkg_v2/hatch_metadata.json b/tests/test_data/packages/basic/base_pkg_v2/hatch_metadata.json index 6ab5ea8..0ce9cb1 100644 --- a/tests/test_data/packages/basic/base_pkg_v2/hatch_metadata.json +++ b/tests/test_data/packages/basic/base_pkg_v2/hatch_metadata.json @@ -27,4 +27,4 @@ "description": "Example tool for base_pkg_v2" } ] -} \ No newline at end of file +} diff --git a/tests/test_data/packages/basic/base_pkg_v2/mcp_server.py b/tests/test_data/packages/basic/base_pkg_v2/mcp_server.py index c61ed6a..7ac04c6 100644 --- a/tests/test_data/packages/basic/base_pkg_v2/mcp_server.py +++ b/tests/test_data/packages/basic/base_pkg_v2/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for base_pkg_v2. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("base_pkg_v2", log_level="WARNING") + @mcp.tool() def base_pkg_v2_tool(param: str) -> str: """Example tool function for base_pkg_v2. @@ -17,5 +19,6 @@ def base_pkg_v2_tool(param: str) -> str: """ return f"Processed by base_pkg_v2: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/basic/utility_pkg/hatch_mcp_server.py b/tests/test_data/packages/basic/utility_pkg/hatch_mcp_server.py index 2db32ea..ca29fb7 100644 --- a/tests/test_data/packages/basic/utility_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/basic/utility_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for utility_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting utility_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/basic/utility_pkg/hatch_metadata.json b/tests/test_data/packages/basic/utility_pkg/hatch_metadata.json index bd15796..aa260a9 100644 --- a/tests/test_data/packages/basic/utility_pkg/hatch_metadata.json +++ b/tests/test_data/packages/basic/utility_pkg/hatch_metadata.json @@ -26,4 +26,4 @@ "description": "Example tool for utility_pkg" } ] -} \ No newline at end of file +} diff --git a/tests/test_data/packages/basic/utility_pkg/mcp_server.py b/tests/test_data/packages/basic/utility_pkg/mcp_server.py index e0aa256..9e74a6e 100644 --- a/tests/test_data/packages/basic/utility_pkg/mcp_server.py +++ b/tests/test_data/packages/basic/utility_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for utility_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("utility_pkg", log_level="WARNING") + @mcp.tool() def utility_pkg_tool(param: str) -> str: """Example tool function for utility_pkg. @@ -17,5 +19,6 @@ def utility_pkg_tool(param: str) -> str: """ return f"Processed by utility_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/dependencies/complex_dep_pkg/hatch_mcp_server.py b/tests/test_data/packages/dependencies/complex_dep_pkg/hatch_mcp_server.py index 863efa2..41cd84b 100644 --- a/tests/test_data/packages/dependencies/complex_dep_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/dependencies/complex_dep_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for complex_dep_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting complex_dep_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/dependencies/complex_dep_pkg/hatch_metadata.json b/tests/test_data/packages/dependencies/complex_dep_pkg/hatch_metadata.json index 50674c0..8e801f0 100644 --- a/tests/test_data/packages/dependencies/complex_dep_pkg/hatch_metadata.json +++ b/tests/test_data/packages/dependencies/complex_dep_pkg/hatch_metadata.json @@ -38,4 +38,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/dependencies/complex_dep_pkg/mcp_server.py b/tests/test_data/packages/dependencies/complex_dep_pkg/mcp_server.py index b9b44e5..cb6e51e 100644 --- a/tests/test_data/packages/dependencies/complex_dep_pkg/mcp_server.py +++ b/tests/test_data/packages/dependencies/complex_dep_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for complex_dep_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("complex_dep_pkg", log_level="WARNING") + @mcp.tool() def complex_dep_pkg_tool(param: str) -> str: """Example tool function for complex_dep_pkg. @@ -17,5 +19,6 @@ def complex_dep_pkg_tool(param: str) -> str: """ return f"Processed by complex_dep_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/dependencies/docker_dep_pkg/hatch_mcp_server.py b/tests/test_data/packages/dependencies/docker_dep_pkg/hatch_mcp_server.py index 52e710b..8d9100c 100644 --- a/tests/test_data/packages/dependencies/docker_dep_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/dependencies/docker_dep_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for docker_dep_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting docker_dep_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/dependencies/docker_dep_pkg/hatch_metadata.json b/tests/test_data/packages/dependencies/docker_dep_pkg/hatch_metadata.json index 1ab16a5..772f4ed 100644 --- a/tests/test_data/packages/dependencies/docker_dep_pkg/hatch_metadata.json +++ b/tests/test_data/packages/dependencies/docker_dep_pkg/hatch_metadata.json @@ -35,4 +35,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/dependencies/docker_dep_pkg/mcp_server.py b/tests/test_data/packages/dependencies/docker_dep_pkg/mcp_server.py index 88d14ba..eaaf8a5 100644 --- a/tests/test_data/packages/dependencies/docker_dep_pkg/mcp_server.py +++ b/tests/test_data/packages/dependencies/docker_dep_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for docker_dep_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("docker_dep_pkg", log_level="WARNING") + @mcp.tool() def docker_dep_pkg_tool(param: str) -> str: """Example tool function for docker_dep_pkg. @@ -17,5 +19,6 @@ def docker_dep_pkg_tool(param: str) -> str: """ return f"Processed by docker_dep_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/dependencies/mixed_dep_pkg/hatch_mcp_server.py b/tests/test_data/packages/dependencies/mixed_dep_pkg/hatch_mcp_server.py index b37ac8a..03998fe 100644 --- a/tests/test_data/packages/dependencies/mixed_dep_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/dependencies/mixed_dep_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for mixed_dep_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting mixed_dep_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/dependencies/mixed_dep_pkg/hatch_metadata.json b/tests/test_data/packages/dependencies/mixed_dep_pkg/hatch_metadata.json index 941fb5f..9d9e14d 100644 --- a/tests/test_data/packages/dependencies/mixed_dep_pkg/hatch_metadata.json +++ b/tests/test_data/packages/dependencies/mixed_dep_pkg/hatch_metadata.json @@ -48,4 +48,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/dependencies/mixed_dep_pkg/mcp_server.py b/tests/test_data/packages/dependencies/mixed_dep_pkg/mcp_server.py index c286204..cd95219 100644 --- a/tests/test_data/packages/dependencies/mixed_dep_pkg/mcp_server.py +++ b/tests/test_data/packages/dependencies/mixed_dep_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for mixed_dep_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("mixed_dep_pkg", log_level="WARNING") + @mcp.tool() def mixed_dep_pkg_tool(param: str) -> str: """Example tool function for mixed_dep_pkg. @@ -17,5 +19,6 @@ def mixed_dep_pkg_tool(param: str) -> str: """ return f"Processed by mixed_dep_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/dependencies/python_dep_pkg/hatch_mcp_server.py b/tests/test_data/packages/dependencies/python_dep_pkg/hatch_mcp_server.py index 3a4e3c5..3726961 100644 --- a/tests/test_data/packages/dependencies/python_dep_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/dependencies/python_dep_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for python_dep_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting python_dep_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/dependencies/python_dep_pkg/hatch_metadata.json b/tests/test_data/packages/dependencies/python_dep_pkg/hatch_metadata.json index e61b1f5..84317fd 100644 --- a/tests/test_data/packages/dependencies/python_dep_pkg/hatch_metadata.json +++ b/tests/test_data/packages/dependencies/python_dep_pkg/hatch_metadata.json @@ -40,4 +40,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/dependencies/python_dep_pkg/mcp_server.py b/tests/test_data/packages/dependencies/python_dep_pkg/mcp_server.py index a50bd20..c4ff275 100644 --- a/tests/test_data/packages/dependencies/python_dep_pkg/mcp_server.py +++ b/tests/test_data/packages/dependencies/python_dep_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for python_dep_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("python_dep_pkg", log_level="WARNING") + @mcp.tool() def python_dep_pkg_tool(param: str) -> str: """Example tool function for python_dep_pkg. @@ -17,5 +19,6 @@ def python_dep_pkg_tool(param: str) -> str: """ return f"Processed by python_dep_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/dependencies/simple_dep_pkg/hatch_mcp_server.py b/tests/test_data/packages/dependencies/simple_dep_pkg/hatch_mcp_server.py index 97891fb..4e23a05 100644 --- a/tests/test_data/packages/dependencies/simple_dep_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/dependencies/simple_dep_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for simple_dep_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting simple_dep_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/dependencies/simple_dep_pkg/hatch_metadata.json b/tests/test_data/packages/dependencies/simple_dep_pkg/hatch_metadata.json index f4928d7..84891ad 100644 --- a/tests/test_data/packages/dependencies/simple_dep_pkg/hatch_metadata.json +++ b/tests/test_data/packages/dependencies/simple_dep_pkg/hatch_metadata.json @@ -34,4 +34,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/dependencies/simple_dep_pkg/mcp_server.py b/tests/test_data/packages/dependencies/simple_dep_pkg/mcp_server.py index 68e7323..b206b23 100644 --- a/tests/test_data/packages/dependencies/simple_dep_pkg/mcp_server.py +++ b/tests/test_data/packages/dependencies/simple_dep_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for simple_dep_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("simple_dep_pkg", log_level="WARNING") + @mcp.tool() def simple_dep_pkg_tool(param: str) -> str: """Example tool function for simple_dep_pkg. @@ -17,5 +19,6 @@ def simple_dep_pkg_tool(param: str) -> str: """ return f"Processed by simple_dep_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/dependencies/system_dep_pkg/hatch_mcp_server.py b/tests/test_data/packages/dependencies/system_dep_pkg/hatch_mcp_server.py index b44b458..5664380 100644 --- a/tests/test_data/packages/dependencies/system_dep_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/dependencies/system_dep_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for system_dep_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting system_dep_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/dependencies/system_dep_pkg/hatch_metadata.json b/tests/test_data/packages/dependencies/system_dep_pkg/hatch_metadata.json index 1977441..2d3463a 100644 --- a/tests/test_data/packages/dependencies/system_dep_pkg/hatch_metadata.json +++ b/tests/test_data/packages/dependencies/system_dep_pkg/hatch_metadata.json @@ -35,4 +35,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/dependencies/system_dep_pkg/mcp_server.py b/tests/test_data/packages/dependencies/system_dep_pkg/mcp_server.py index dfa6196..431b4df 100644 --- a/tests/test_data/packages/dependencies/system_dep_pkg/mcp_server.py +++ b/tests/test_data/packages/dependencies/system_dep_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for system_dep_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("system_dep_pkg", log_level="WARNING") + @mcp.tool() def system_dep_pkg_tool(param: str) -> str: """Example tool function for system_dep_pkg. @@ -17,5 +19,6 @@ def system_dep_pkg_tool(param: str) -> str: """ return f"Processed by system_dep_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/error_scenarios/circular_dep_pkg/hatch_mcp_server.py b/tests/test_data/packages/error_scenarios/circular_dep_pkg/hatch_mcp_server.py index d69698d..ad26b72 100644 --- a/tests/test_data/packages/error_scenarios/circular_dep_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/error_scenarios/circular_dep_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for circular_dep_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting circular_dep_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/error_scenarios/circular_dep_pkg/hatch_metadata.json b/tests/test_data/packages/error_scenarios/circular_dep_pkg/hatch_metadata.json index 8171758..29df902 100644 --- a/tests/test_data/packages/error_scenarios/circular_dep_pkg/hatch_metadata.json +++ b/tests/test_data/packages/error_scenarios/circular_dep_pkg/hatch_metadata.json @@ -34,4 +34,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/error_scenarios/circular_dep_pkg/mcp_server.py b/tests/test_data/packages/error_scenarios/circular_dep_pkg/mcp_server.py index 0909d22..f705d88 100644 --- a/tests/test_data/packages/error_scenarios/circular_dep_pkg/mcp_server.py +++ b/tests/test_data/packages/error_scenarios/circular_dep_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for circular_dep_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("circular_dep_pkg", log_level="WARNING") + @mcp.tool() def circular_dep_pkg_tool(param: str) -> str: """Example tool function for circular_dep_pkg. @@ -17,5 +19,6 @@ def circular_dep_pkg_tool(param: str) -> str: """ return f"Processed by circular_dep_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/hatch_mcp_server.py b/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/hatch_mcp_server.py index c979c43..d18e997 100644 --- a/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/hatch_mcp_server.py +++ b/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for circular_dep_pkg_b. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting circular_dep_pkg_b via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/hatch_metadata.json b/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/hatch_metadata.json index e783351..6cf7538 100644 --- a/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/hatch_metadata.json +++ b/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/hatch_metadata.json @@ -35,4 +35,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/mcp_server.py b/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/mcp_server.py index c7a8b65..65f5e23 100644 --- a/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/mcp_server.py +++ b/tests/test_data/packages/error_scenarios/circular_dep_pkg_b/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for circular_dep_pkg_b. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("circular_dep_pkg_b", log_level="WARNING") + @mcp.tool() def circular_dep_pkg_b_tool(param: str) -> str: """Example tool function for circular_dep_pkg_b. @@ -17,5 +19,6 @@ def circular_dep_pkg_b_tool(param: str) -> str: """ return f"Processed by circular_dep_pkg_b: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/error_scenarios/invalid_dep_pkg/hatch_mcp_server.py b/tests/test_data/packages/error_scenarios/invalid_dep_pkg/hatch_mcp_server.py index 61bf12c..28a34a5 100644 --- a/tests/test_data/packages/error_scenarios/invalid_dep_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/error_scenarios/invalid_dep_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for invalid_dep_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting invalid_dep_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/error_scenarios/invalid_dep_pkg/hatch_metadata.json b/tests/test_data/packages/error_scenarios/invalid_dep_pkg/hatch_metadata.json index 6b62910..224b46c 100644 --- a/tests/test_data/packages/error_scenarios/invalid_dep_pkg/hatch_metadata.json +++ b/tests/test_data/packages/error_scenarios/invalid_dep_pkg/hatch_metadata.json @@ -34,4 +34,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/error_scenarios/invalid_dep_pkg/mcp_server.py b/tests/test_data/packages/error_scenarios/invalid_dep_pkg/mcp_server.py index 239bed1..c6741bd 100644 --- a/tests/test_data/packages/error_scenarios/invalid_dep_pkg/mcp_server.py +++ b/tests/test_data/packages/error_scenarios/invalid_dep_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for invalid_dep_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("invalid_dep_pkg", log_level="WARNING") + @mcp.tool() def invalid_dep_pkg_tool(param: str) -> str: """Example tool function for invalid_dep_pkg. @@ -17,5 +19,6 @@ def invalid_dep_pkg_tool(param: str) -> str: """ return f"Processed by invalid_dep_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/error_scenarios/version_conflict_pkg/hatch_mcp_server.py b/tests/test_data/packages/error_scenarios/version_conflict_pkg/hatch_mcp_server.py index 53c7bcb..8467e36 100644 --- a/tests/test_data/packages/error_scenarios/version_conflict_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/error_scenarios/version_conflict_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for version_conflict_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting version_conflict_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/error_scenarios/version_conflict_pkg/hatch_metadata.json b/tests/test_data/packages/error_scenarios/version_conflict_pkg/hatch_metadata.json index 6a327fd..980c12f 100644 --- a/tests/test_data/packages/error_scenarios/version_conflict_pkg/hatch_metadata.json +++ b/tests/test_data/packages/error_scenarios/version_conflict_pkg/hatch_metadata.json @@ -34,4 +34,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/error_scenarios/version_conflict_pkg/mcp_server.py b/tests/test_data/packages/error_scenarios/version_conflict_pkg/mcp_server.py index 024cd41..5a7aec7 100644 --- a/tests/test_data/packages/error_scenarios/version_conflict_pkg/mcp_server.py +++ b/tests/test_data/packages/error_scenarios/version_conflict_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for version_conflict_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("version_conflict_pkg", log_level="WARNING") + @mcp.tool() def version_conflict_pkg_tool(param: str) -> str: """Example tool function for version_conflict_pkg. @@ -17,5 +19,6 @@ def version_conflict_pkg_tool(param: str) -> str: """ return f"Processed by version_conflict_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data/packages/schema_versions/schema_v1_1_0_pkg/hatch_metadata.json b/tests/test_data/packages/schema_versions/schema_v1_1_0_pkg/hatch_metadata.json index 59c0d9f..40c88af 100644 --- a/tests/test_data/packages/schema_versions/schema_v1_1_0_pkg/hatch_metadata.json +++ b/tests/test_data/packages/schema_versions/schema_v1_1_0_pkg/hatch_metadata.json @@ -26,4 +26,4 @@ "version_constraint": ">=1.0.0" } ] -} \ No newline at end of file +} diff --git a/tests/test_data/packages/schema_versions/schema_v1_1_0_pkg/main.py b/tests/test_data/packages/schema_versions/schema_v1_1_0_pkg/main.py index fd918bd..c082b44 100644 --- a/tests/test_data/packages/schema_versions/schema_v1_1_0_pkg/main.py +++ b/tests/test_data/packages/schema_versions/schema_v1_1_0_pkg/main.py @@ -2,10 +2,12 @@ Test package: schema_v1_1_0_pkg """ + def main(): """Main entry point for schema_v1_1_0_pkg.""" print("Hello from schema_v1_1_0_pkg!") return "schema_v1_1_0_pkg executed successfully" + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/schema_versions/schema_v1_2_0_pkg/hatch_metadata.json b/tests/test_data/packages/schema_versions/schema_v1_2_0_pkg/hatch_metadata.json index 657aa2b..07f4e11 100644 --- a/tests/test_data/packages/schema_versions/schema_v1_2_0_pkg/hatch_metadata.json +++ b/tests/test_data/packages/schema_versions/schema_v1_2_0_pkg/hatch_metadata.json @@ -31,4 +31,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/schema_versions/schema_v1_2_0_pkg/main.py b/tests/test_data/packages/schema_versions/schema_v1_2_0_pkg/main.py index 43bdb4d..181f589 100644 --- a/tests/test_data/packages/schema_versions/schema_v1_2_0_pkg/main.py +++ b/tests/test_data/packages/schema_versions/schema_v1_2_0_pkg/main.py @@ -2,10 +2,12 @@ Test package: schema_v1_2_0_pkg """ + def main(): """Main entry point for schema_v1_2_0_pkg.""" print("Hello from schema_v1_2_0_pkg!") return "schema_v1_2_0_pkg executed successfully" + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/hatch_mcp_server.py b/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/hatch_mcp_server.py index e723451..be24a61 100644 --- a/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/hatch_mcp_server.py +++ b/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/hatch_mcp_server.py @@ -1,6 +1,7 @@ """ HatchMCP wrapper for schema_v1_2_1_pkg. """ + import sys from pathlib import Path @@ -9,10 +10,12 @@ from mcp_server import mcp + def main(): """Main entry point for HatchMCP wrapper.""" print("Starting schema_v1_2_1_pkg via HatchMCP wrapper") mcp.run() + if __name__ == "__main__": main() diff --git a/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/hatch_metadata.json b/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/hatch_metadata.json index 521135c..e8e8e81 100644 --- a/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/hatch_metadata.json +++ b/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/hatch_metadata.json @@ -34,4 +34,4 @@ } ] } -} \ No newline at end of file +} diff --git a/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/mcp_server.py b/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/mcp_server.py index b008ad7..40d76a0 100644 --- a/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/mcp_server.py +++ b/tests/test_data/packages/schema_versions/schema_v1_2_1_pkg/mcp_server.py @@ -1,10 +1,12 @@ """ FastMCP server implementation for schema_v1_2_1_pkg. """ + from mcp.server.fastmcp import FastMCP mcp = FastMCP("schema_v1_2_1_pkg", log_level="WARNING") + @mcp.tool() def schema_v1_2_1_pkg_tool(param: str) -> str: """Example tool function for schema_v1_2_1_pkg. @@ -17,5 +19,6 @@ def schema_v1_2_1_pkg_tool(param: str) -> str: """ return f"Processed by schema_v1_2_1_pkg: {param}" + if __name__ == "__main__": mcp.run() diff --git a/tests/test_data_utils.py b/tests/test_data_utils.py index 59739a6..9ed7559 100644 --- a/tests/test_data_utils.py +++ b/tests/test_data_utils.py @@ -11,25 +11,25 @@ class TestDataLoader: """Utility class for loading test data from standardized locations.""" - + def __init__(self): """Initialize the test data loader.""" self.test_data_dir = Path(__file__).parent / "test_data" self.configs_dir = self.test_data_dir / "configs" self.responses_dir = self.test_data_dir / "responses" self.packages_dir = self.test_data_dir / "packages" - + # Ensure directories exist self.configs_dir.mkdir(parents=True, exist_ok=True) self.responses_dir.mkdir(parents=True, exist_ok=True) self.packages_dir.mkdir(parents=True, exist_ok=True) - + def load_config(self, config_name: str) -> Dict[str, Any]: """Load a test configuration file. - + Args: config_name: Name of the config file (without .json extension) - + Returns: Loaded configuration as a dictionary """ @@ -37,16 +37,16 @@ def load_config(self, config_name: str) -> Dict[str, Any]: if not config_path.exists(): # Create default config if it doesn't exist self._create_default_config(config_name) - - with open(config_path, 'r') as f: + + with open(config_path, "r") as f: return json.load(f) - + def load_response(self, response_name: str) -> Dict[str, Any]: """Load a mock response file. - + Args: response_name: Name of the response file (without .json extension) - + Returns: Loaded response as a dictionary """ @@ -54,28 +54,28 @@ def load_response(self, response_name: str) -> Dict[str, Any]: if not response_path.exists(): # Create default response if it doesn't exist self._create_default_response(response_name) - - with open(response_path, 'r') as f: + + with open(response_path, "r") as f: return json.load(f) - + def setup(self): """Set up test data (placeholder for future setup logic).""" # Currently no setup needed as test packages are static pass - + def cleanup(self): """Clean up test data (placeholder for future cleanup logic).""" # Currently no cleanup needed as test packages are persistent pass - + def get_test_packages_dir(self) -> Path: """Get the test packages directory path. - + Returns: Path to the test packages directory """ return self.packages_dir - + def _create_default_config(self, config_name: str): """Create a default configuration file.""" default_configs = { @@ -83,43 +83,31 @@ def _create_default_config(self, config_name: str): "test_timeout": 30, "temp_dir_prefix": "hatch_test_", "cleanup_temp_dirs": True, - "mock_external_services": True + "mock_external_services": True, }, "installer_configs": { - "python_installer": { - "pip_timeout": 60, - "use_cache": False - }, - "docker_installer": { - "timeout": 120, - "cleanup_containers": True - } - } + "python_installer": {"pip_timeout": 60, "use_cache": False}, + "docker_installer": {"timeout": 120, "cleanup_containers": True}, + }, } - + config = default_configs.get(config_name, {}) config_path = self.configs_dir / f"{config_name}.json" - with open(config_path, 'w') as f: + with open(config_path, "w") as f: json.dump(config, f, indent=2) - + def _create_default_response(self, response_name: str): """Create a default response file.""" default_responses = { "registry_responses": { - "success": { - "status": "success", - "data": {"packages": []} - }, - "error": { - "status": "error", - "message": "Registry not available" - } + "success": {"status": "success", "data": {"packages": []}}, + "error": {"status": "error", "message": "Registry not available"}, } } - + response = default_responses.get(response_name, {}) response_path = self.responses_dir / f"{response_name}.json" - with open(response_path, 'w') as f: + with open(response_path, "w") as f: json.dump(response, f, indent=2) def load_fixture(self, fixture_name: str) -> Dict[str, Any]: @@ -133,7 +121,7 @@ def load_fixture(self, fixture_name: str) -> Dict[str, Any]: """ fixtures_dir = self.test_data_dir / "fixtures" fixture_path = fixtures_dir / f"{fixture_name}.json" - with open(fixture_path, 'r') as f: + with open(fixture_path, "r") as f: return json.load(f) @@ -187,6 +175,7 @@ def get_logging_messages(self) -> Dict[str, str]: config = self.get_non_tty_config() return config["logging_messages"] + class MCPBackupTestDataLoader(TestDataLoader): """Specialized test data loader for MCP backup system tests.""" @@ -208,39 +197,39 @@ def load_host_agnostic_config(self, config_type: str) -> Dict[str, Any]: if not config_path.exists(): self._create_default_mcp_config(config_type) - with open(config_path, 'r') as f: + with open(config_path, "r") as f: return json.load(f) def _create_default_mcp_config(self, config_type: str): """Create default host-agnostic MCP configuration.""" default_configs = { "simple_server": { - "servers": { - "test_server": { - "command": "python", - "args": ["server.py"] - } - } + "servers": {"test_server": {"command": "python", "args": ["server.py"]}} }, "complex_server": { "servers": { "server1": {"command": "python", "args": ["server1.py"]}, "server2": {"command": "node", "args": ["server2.js"]}, - "server3": {"command": "python", "args": ["server3.py"], "env": {"API_KEY": "test"}} + "server3": { + "command": "python", + "args": ["server3.py"], + "env": {"API_KEY": "test"}, + }, } }, - "empty_config": {"servers": {}} + "empty_config": {"servers": {}}, } config = default_configs.get(config_type, {"servers": {}}) config_path = self.mcp_backup_configs_dir / f"{config_type}.json" - with open(config_path, 'w') as f: + with open(config_path, "w") as f: json.dump(config, f, indent=2) # Global instance for easy access test_data = TestDataLoader() + # Convenience functions def load_test_config(config_name: str) -> Dict[str, Any]: """Load test configuration.""" @@ -265,22 +254,26 @@ def __init__(self): self.mcp_host_configs_dir = self.configs_dir / "mcp_host_test_configs" self.mcp_host_configs_dir.mkdir(exist_ok=True) - def load_host_config_template(self, host_type: str, config_type: str = "simple") -> Dict[str, Any]: + def load_host_config_template( + self, host_type: str, config_type: str = "simple" + ) -> Dict[str, Any]: """Load host-specific configuration template.""" config_path = self.mcp_host_configs_dir / f"{host_type}_{config_type}.json" if not config_path.exists(): self._create_host_config_template(host_type, config_type) - with open(config_path, 'r') as f: + with open(config_path, "r") as f: return json.load(f) - def load_corrected_environment_data(self, data_type: str = "simple") -> Dict[str, Any]: + def load_corrected_environment_data( + self, data_type: str = "simple" + ) -> Dict[str, Any]: """Load corrected environment data structure (v2).""" config_path = self.mcp_host_configs_dir / f"environment_v2_{data_type}.json" if not config_path.exists(): self._create_corrected_environment_data(data_type) - with open(config_path, 'r') as f: + with open(config_path, "r") as f: return json.load(f) def load_mcp_server_config(self, server_type: str = "local") -> Dict[str, Any]: @@ -289,18 +282,18 @@ def load_mcp_server_config(self, server_type: str = "local") -> Dict[str, Any]: if not config_path.exists(): self._create_mcp_server_config(server_type) - with open(config_path, 'r') as f: + with open(config_path, "r") as f: return json.load(f) def load_kiro_mcp_config(self, config_type: str = "empty") -> Dict[str, Any]: """Load Kiro-specific MCP configuration templates. - + Args: config_type: Type of Kiro configuration to load - "empty": Empty mcpServers configuration - "with_server": Single server with all Kiro fields - "complex": Multi-server with mixed configurations - + Returns: Kiro MCP configuration dictionary """ @@ -308,7 +301,7 @@ def load_kiro_mcp_config(self, config_type: str = "empty") -> Dict[str, Any]: if not config_path.exists(): self._create_kiro_mcp_config(config_type) - with open(config_path, 'r') as f: + with open(config_path, "r") as f: return json.load(f) def _create_host_config_template(self, host_type: str, config_type: str): @@ -320,30 +313,29 @@ def _create_host_config_template(self, host_type: str, config_type: str): "test_server": { "command": "/usr/local/bin/python", # Absolute path required "args": ["server.py"], - "env": {"API_KEY": "test"} + "env": {"API_KEY": "test"}, } }, "theme": "dark", # Claude-specific settings - "auto_update": True + "auto_update": True, }, "claude-code_simple": { "mcpServers": { "test_server": { "command": "/usr/local/bin/python", # Absolute path required "args": ["server.py"], - "env": {} + "env": {}, } }, - "workspace_settings": {"mcp_enabled": True} # Claude Code specific + "workspace_settings": {"mcp_enabled": True}, # Claude Code specific }, - # Cursor family templates "cursor_simple": { "mcpServers": { "test_server": { "command": "python", # Flexible path handling "args": ["server.py"], - "env": {"API_KEY": "test"} + "env": {"API_KEY": "test"}, } } }, @@ -351,7 +343,7 @@ def _create_host_config_template(self, host_type: str, config_type: str): "mcpServers": { "remote_server": { "url": "https://api.example.com/mcp", - "headers": {"Authorization": "Bearer token"} + "headers": {"Authorization": "Bearer token"}, } } }, @@ -360,31 +352,23 @@ def _create_host_config_template(self, host_type: str, config_type: str): "test_server": { "command": "python", # Inherits Cursor format "args": ["server.py"], - "env": {} + "env": {}, } } }, - # Independent strategy templates "vscode_simple": { "mcp": { "servers": { - "test_server": { - "command": "python", - "args": ["server.py"] - } + "test_server": {"command": "python", "args": ["server.py"]} } } }, "gemini_simple": { "mcpServers": { - "test_server": { - "command": "python", - "args": ["server.py"] - } + "test_server": {"command": "python", "args": ["server.py"]} } }, - # Kiro family templates "kiro_simple": { "mcpServers": { @@ -392,7 +376,7 @@ def _create_host_config_template(self, host_type: str, config_type: str): "command": "auggie", "args": ["--mcp"], "disabled": False, - "autoApprove": ["codebase-retrieval"] + "autoApprove": ["codebase-retrieval"], } } }, @@ -404,7 +388,7 @@ def _create_host_config_template(self, host_type: str, config_type: str): "env": {"DEBUG": "true"}, "disabled": False, "autoApprove": ["codebase-retrieval", "fetch"], - "disabledTools": ["dangerous-tool"] + "disabledTools": ["dangerous-tool"], } } }, @@ -414,26 +398,23 @@ def _create_host_config_template(self, host_type: str, config_type: str): "command": "auggie", "args": ["--mcp"], "disabled": False, - "autoApprove": ["codebase-retrieval"] + "autoApprove": ["codebase-retrieval"], }, "remote-server": { "url": "https://api.example.com/mcp", "headers": {"Authorization": "Bearer token"}, "disabled": True, - "disabledTools": ["risky-tool"] - } + "disabledTools": ["risky-tool"], + }, }, - "otherSettings": { - "theme": "dark", - "fontSize": 14 - } - } + "otherSettings": {"theme": "dark", "fontSize": 14}, + }, } template_key = f"{host_type}_{config_type}" config = templates.get(template_key, {"mcpServers": {}}) config_path = self.mcp_host_configs_dir / f"{template_key}.json" - with open(config_path, 'w') as f: + with open(config_path, "w") as f: json.dump(config, f, indent=2) def _create_corrected_environment_data(self, data_type: str): @@ -458,12 +439,12 @@ def _create_corrected_environment_data(self, data_type: str): "server_config": { "command": "/usr/local/bin/python", "args": ["weather.py"], - "env": {"API_KEY": "weather_key"} - } + "env": {"API_KEY": "weather_key"}, + }, } - } + }, } - ] + ], }, "multi_host": { "name": "multi_host_environment", @@ -484,8 +465,8 @@ def _create_corrected_environment_data(self, data_type: str): "server_config": { "command": "/usr/local/bin/python", "args": ["file_manager.py"], - "env": {"DEBUG": "true"} - } + "env": {"DEBUG": "true"}, + }, }, "cursor": { "config_path": "~/.cursor/mcp.json", @@ -494,18 +475,18 @@ def _create_corrected_environment_data(self, data_type: str): "server_config": { "command": "python", "args": ["file_manager.py"], - "env": {"DEBUG": "true"} - } - } - } + "env": {"DEBUG": "true"}, + }, + }, + }, } - ] - } + ], + }, } config = templates.get(data_type, {"packages": []}) config_path = self.mcp_host_configs_dir / f"environment_v2_{data_type}.json" - with open(config_path, 'w') as f: + with open(config_path, "w") as f: json.dump(config, f, indent=2) def _create_mcp_server_config(self, server_type: str): @@ -514,32 +495,28 @@ def _create_mcp_server_config(self, server_type: str): "local": { "command": "python", "args": ["server.py", "--port", "8080"], - "env": {"API_KEY": "test", "DEBUG": "true"} + "env": {"API_KEY": "test", "DEBUG": "true"}, }, "remote": { "url": "https://api.example.com/mcp", - "headers": {"Authorization": "Bearer token", "Content-Type": "application/json"} - }, - "local_minimal": { - "command": "python", - "args": ["minimal_server.py"] + "headers": { + "Authorization": "Bearer token", + "Content-Type": "application/json", + }, }, - "remote_minimal": { - "url": "https://minimal.example.com/mcp" - } + "local_minimal": {"command": "python", "args": ["minimal_server.py"]}, + "remote_minimal": {"url": "https://minimal.example.com/mcp"}, } config = templates.get(server_type, {}) config_path = self.mcp_host_configs_dir / f"mcp_server_{server_type}.json" - with open(config_path, 'w') as f: + with open(config_path, "w") as f: json.dump(config, f, indent=2) def _create_kiro_mcp_config(self, config_type: str): """Create Kiro-specific MCP configuration templates.""" templates = { - "empty": { - "mcpServers": {} - }, + "empty": {"mcpServers": {}}, "with_server": { "mcpServers": { "existing-server": { @@ -548,7 +525,7 @@ def _create_kiro_mcp_config(self, config_type: str): "env": {"DEBUG": "true"}, "disabled": False, "autoApprove": ["codebase-retrieval", "fetch"], - "disabledTools": ["dangerous-tool"] + "disabledTools": ["dangerous-tool"], } } }, @@ -558,23 +535,20 @@ def _create_kiro_mcp_config(self, config_type: str): "command": "auggie", "args": ["--mcp"], "disabled": False, - "autoApprove": ["codebase-retrieval"] + "autoApprove": ["codebase-retrieval"], }, "remote-server": { "url": "https://api.example.com/mcp", "headers": {"Authorization": "Bearer token"}, "disabled": True, - "disabledTools": ["risky-tool"] - } + "disabledTools": ["risky-tool"], + }, }, - "otherSettings": { - "theme": "dark", - "fontSize": 14 - } - } + "otherSettings": {"theme": "dark", "fontSize": 14}, + }, } - + config = templates.get(config_type, {"mcpServers": {}}) config_path = self.mcp_host_configs_dir / f"kiro_mcp_{config_type}.json" - with open(config_path, 'w') as f: + with open(config_path, "w") as f: json.dump(config, f, indent=2) diff --git a/tests/test_dependency_orchestrator_consent.py b/tests/test_dependency_orchestrator_consent.py index 2bf75b2..c375763 100644 --- a/tests/test_dependency_orchestrator_consent.py +++ b/tests/test_dependency_orchestrator_consent.py @@ -7,9 +7,10 @@ import unittest import os -import sys from unittest.mock import patch, MagicMock -from hatch.installers.dependency_installation_orchestrator import DependencyInstallerOrchestrator +from hatch.installers.dependency_installation_orchestrator import ( + DependencyInstallerOrchestrator, +) from hatch.package_loader import HatchPackageLoader from hatch_validator.registry.registry_service import RegistryService from wobble.decorators import regression_test @@ -18,249 +19,275 @@ class TestUserConsentHandling(unittest.TestCase): """Test user consent handling in dependency installation orchestrator.""" - + def setUp(self): """Set up test environment with centralized test data.""" # Create mock dependencies for orchestrator self.mock_package_loader = MagicMock(spec=HatchPackageLoader) - self.mock_registry_data = {"registry_schema_version": "1.1.0", "repositories": []} + self.mock_registry_data = { + "registry_schema_version": "1.1.0", + "repositories": [], + } self.mock_registry_service = MagicMock(spec=RegistryService) # Create orchestrator with mocked dependencies self.orchestrator = DependencyInstallerOrchestrator( package_loader=self.mock_package_loader, registry_service=self.mock_registry_service, - registry_data=self.mock_registry_data + registry_data=self.mock_registry_data, ) self.test_data = NonTTYTestDataLoader() - self.mock_install_plan = self.test_data.get_installation_plan("basic_python_plan") + self.mock_install_plan = self.test_data.get_installation_plan( + "basic_python_plan" + ) self.logging_messages = self.test_data.get_logging_messages() - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', return_value='y') + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", return_value="y") def test_tty_environment_user_approves(self, mock_input, mock_isatty): """Test user consent approval in TTY environment.""" result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertTrue(result) mock_input.assert_called_once_with("\nProceed with installation? [y/N]: ") mock_isatty.assert_called_once() - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', return_value='yes') + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", return_value="yes") def test_tty_environment_user_approves_full_word(self, mock_input, mock_isatty): """Test user consent approval with 'yes' in TTY environment.""" result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertTrue(result) mock_input.assert_called_once_with("\nProceed with installation? [y/N]: ") - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', return_value='n') + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", return_value="n") def test_tty_environment_user_denies(self, mock_input, mock_isatty): """Test user consent denial in TTY environment.""" result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertFalse(result) mock_input.assert_called_once_with("\nProceed with installation? [y/N]: ") - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', return_value='no') + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", return_value="no") def test_tty_environment_user_denies_full_word(self, mock_input, mock_isatty): """Test user consent denial with 'no' in TTY environment.""" result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertFalse(result) mock_input.assert_called_once_with("\nProceed with installation? [y/N]: ") - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', return_value='') + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", return_value="") def test_tty_environment_user_default_deny(self, mock_input, mock_isatty): """Test user consent default (empty) response in TTY environment.""" result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertFalse(result) mock_input.assert_called_once_with("\nProceed with installation? [y/N]: ") - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', side_effect=['invalid', 'y']) - @patch('builtins.print') - def test_tty_environment_invalid_then_valid_input(self, mock_print, mock_input, mock_isatty): + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", side_effect=["invalid", "y"]) + @patch("builtins.print") + def test_tty_environment_invalid_then_valid_input( + self, mock_print, mock_input, mock_isatty + ): """Test handling of invalid input followed by valid input.""" result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertTrue(result) self.assertEqual(mock_input.call_count, 2) mock_print.assert_called_once_with("Please enter 'y' for yes or 'n' for no.") - + @regression_test - @patch('sys.stdin.isatty', return_value=False) + @patch("sys.stdin.isatty", return_value=False) def test_non_tty_environment_auto_approve(self, mock_isatty): """Test automatic approval in non-TTY environment.""" - with patch.object(self.orchestrator.logger, 'info') as mock_log: + with patch.object(self.orchestrator.logger, "info") as mock_log: result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertTrue(result) mock_isatty.assert_called_once() mock_log.assert_called_with(self.logging_messages["auto_approve"]) - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': '1'}) + @patch("sys.stdin.isatty", return_value=True) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "1"}) def test_environment_variable_numeric_true(self, mock_isatty): """Test HATCH_AUTO_APPROVE=1 triggers auto-approval.""" - with patch.object(self.orchestrator.logger, 'info') as mock_log: + with patch.object(self.orchestrator.logger, "info") as mock_log: result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertTrue(result) mock_log.assert_called_with(self.logging_messages["auto_approve"]) - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': 'true'}) + @patch("sys.stdin.isatty", return_value=True) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "true"}) def test_environment_variable_string_true(self, mock_isatty): """Test HATCH_AUTO_APPROVE=true triggers auto-approval.""" - with patch.object(self.orchestrator.logger, 'info') as mock_log: + with patch.object(self.orchestrator.logger, "info") as mock_log: result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertTrue(result) mock_log.assert_called_with(self.logging_messages["auto_approve"]) - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': 'YES'}) + @patch("sys.stdin.isatty", return_value=True) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "YES"}) def test_environment_variable_case_insensitive(self, mock_isatty): """Test HATCH_AUTO_APPROVE is case-insensitive.""" - with patch.object(self.orchestrator.logger, 'info') as mock_log: + with patch.object(self.orchestrator.logger, "info") as mock_log: result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertTrue(result) mock_log.assert_called_with(self.logging_messages["auto_approve"]) - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': 'invalid'}) - @patch('builtins.input', return_value='y') + @patch("sys.stdin.isatty", return_value=True) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "invalid"}) + @patch("builtins.input", return_value="y") def test_environment_variable_invalid_value(self, mock_input, mock_isatty): """Test invalid HATCH_AUTO_APPROVE value falls back to TTY behavior.""" result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertTrue(result) mock_input.assert_called_once() - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', side_effect=EOFError()) + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", side_effect=EOFError()) def test_eof_error_handling(self, mock_input, mock_isatty): """Test EOFError handling in interactive mode.""" - with patch.object(self.orchestrator.logger, 'info') as mock_log: + with patch.object(self.orchestrator.logger, "info") as mock_log: result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertFalse(result) mock_log.assert_called_with(self.logging_messages["user_cancelled"]) - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', side_effect=KeyboardInterrupt()) + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", side_effect=KeyboardInterrupt()) def test_keyboard_interrupt_handling(self, mock_input, mock_isatty): """Test KeyboardInterrupt handling in interactive mode.""" - with patch.object(self.orchestrator.logger, 'info') as mock_log: + with patch.object(self.orchestrator.logger, "info") as mock_log: result = self.orchestrator._request_user_consent(self.mock_install_plan) - + self.assertFalse(result) mock_log.assert_called_with(self.logging_messages["user_cancelled"]) class TestEnvironmentVariableScenarios(unittest.TestCase): """Test comprehensive environment variable scenarios using centralized test data.""" - + def setUp(self): """Set up test environment with centralized test data.""" # Create mock dependencies for orchestrator self.mock_package_loader = MagicMock(spec=HatchPackageLoader) - self.mock_registry_data = {"registry_schema_version": "1.1.0", "repositories": []} + self.mock_registry_data = { + "registry_schema_version": "1.1.0", + "repositories": [], + } self.mock_registry_service = MagicMock(spec=RegistryService) # Create orchestrator with mocked dependencies self.orchestrator = DependencyInstallerOrchestrator( package_loader=self.mock_package_loader, registry_service=self.mock_registry_service, - registry_data=self.mock_registry_data + registry_data=self.mock_registry_data, ) self.test_data = NonTTYTestDataLoader() - self.mock_install_plan = self.test_data.get_installation_plan("basic_python_plan") + self.mock_install_plan = self.test_data.get_installation_plan( + "basic_python_plan" + ) self.env_scenarios = self.test_data.get_environment_variable_scenarios() self.logging_messages = self.test_data.get_logging_messages() - + @regression_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', return_value='n') # Mock input for fallback cases to deny + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", return_value="n") # Mock input for fallback cases to deny def test_all_environment_variable_scenarios(self, mock_input, mock_isatty): """Test all environment variable scenarios from centralized test data.""" for scenario in self.env_scenarios: with self.subTest(scenario=scenario["name"]): - with patch.dict(os.environ, {'HATCH_AUTO_APPROVE': scenario["value"]}): - with patch.object(self.orchestrator.logger, 'info') as mock_log: - result = self.orchestrator._request_user_consent(self.mock_install_plan) + with patch.dict(os.environ, {"HATCH_AUTO_APPROVE": scenario["value"]}): + with patch.object(self.orchestrator.logger, "info") as mock_log: + result = self.orchestrator._request_user_consent( + self.mock_install_plan + ) - self.assertEqual(result, scenario["expected"], - f"Failed for scenario: {scenario['name']} with value: {scenario['value']}") + self.assertEqual( + result, + scenario["expected"], + f"Failed for scenario: {scenario['name']} with value: {scenario['value']}", + ) if scenario["expected"]: - mock_log.assert_called_with(self.logging_messages["auto_approve"]) + mock_log.assert_called_with( + self.logging_messages["auto_approve"] + ) class TestInstallationPlanVariations(unittest.TestCase): """Test consent handling with different installation plan variations.""" - + def setUp(self): """Set up test environment with centralized test data.""" # Create mock dependencies for orchestrator self.mock_package_loader = MagicMock(spec=HatchPackageLoader) - self.mock_registry_data = {"registry_schema_version": "1.1.0", "repositories": []} + self.mock_registry_data = { + "registry_schema_version": "1.1.0", + "repositories": [], + } self.mock_registry_service = MagicMock(spec=RegistryService) # Create orchestrator with mocked dependencies self.orchestrator = DependencyInstallerOrchestrator( package_loader=self.mock_package_loader, registry_service=self.mock_registry_service, - registry_data=self.mock_registry_data + registry_data=self.mock_registry_data, ) self.test_data = NonTTYTestDataLoader() - + @regression_test - @patch('sys.stdin.isatty', return_value=False) + @patch("sys.stdin.isatty", return_value=False) def test_non_tty_with_empty_plan(self, mock_isatty): """Test non-TTY behavior with empty installation plan.""" empty_plan = self.test_data.get_installation_plan("empty_plan") - - with patch.object(self.orchestrator.logger, 'info') as mock_log: + + with patch.object(self.orchestrator.logger, "info") as mock_log: result = self.orchestrator._request_user_consent(empty_plan) - + self.assertTrue(result) - mock_log.assert_called_with(self.test_data.get_logging_messages()["auto_approve"]) - + mock_log.assert_called_with( + self.test_data.get_logging_messages()["auto_approve"] + ) + @regression_test - @patch('sys.stdin.isatty', return_value=False) + @patch("sys.stdin.isatty", return_value=False) def test_non_tty_with_complex_plan(self, mock_isatty): """Test non-TTY behavior with complex installation plan.""" complex_plan = self.test_data.get_installation_plan("complex_plan") - - with patch.object(self.orchestrator.logger, 'info') as mock_log: + + with patch.object(self.orchestrator.logger, "info") as mock_log: result = self.orchestrator._request_user_consent(complex_plan) - + self.assertTrue(result) - mock_log.assert_called_with(self.test_data.get_logging_messages()["auto_approve"]) + mock_log.assert_called_with( + self.test_data.get_logging_messages()["auto_approve"] + ) -if __name__ == '__main__': +if __name__ == "__main__": unittest.main() diff --git a/tests/test_docker_installer.py b/tests/test_docker_installer.py index 310175c..3b7b245 100644 --- a/tests/test_docker_installer.py +++ b/tests/test_docker_installer.py @@ -4,26 +4,35 @@ including unit tests with mocked Docker client and integration tests with real Docker images. """ + import unittest import tempfile import shutil from pathlib import Path -from unittest.mock import patch, MagicMock, Mock -from typing import Dict, Any +from unittest.mock import patch, Mock -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test, integration_test -from hatch.installers.docker_installer import DockerInstaller, DOCKER_AVAILABLE, DOCKER_DAEMON_AVAILABLE +from hatch.installers.docker_installer import ( + DockerInstaller, + DOCKER_AVAILABLE, + DOCKER_DAEMON_AVAILABLE, +) from hatch.installers.installer_base import InstallationError -from hatch.installers.installation_context import InstallationContext, InstallationResult, InstallationStatus +from hatch.installers.installation_context import ( + InstallationContext, + InstallationStatus, +) class DummyContext(InstallationContext): """Test implementation of InstallationContext.""" - - def __init__(self, env_path=None, env_name=None, simulation_mode=False, extra_config=None): + + def __init__( + self, env_path=None, env_name=None, simulation_mode=False, extra_config=None + ): """Initialize dummy context. - + Args: env_path (Optional[Path]): Environment path. env_name (Optional[str]): Environment name. @@ -37,11 +46,11 @@ def __init__(self, env_path=None, env_name=None, simulation_mode=False, extra_co def get_config(self, key, default=None): """Get configuration value. - + Args: key (str): Configuration key. default: Default value if key not found. - + Returns: Configuration value or default. """ @@ -55,10 +64,7 @@ def setUp(self): """Set up test fixtures.""" self.installer = DockerInstaller() self.temp_dir = tempfile.mkdtemp() - self.context = DummyContext( - env_path=Path(self.temp_dir), - simulation_mode=False - ) + self.context = DummyContext(env_path=Path(self.temp_dir), simulation_mode=False) def tearDown(self): """Clean up test fixtures.""" @@ -68,16 +74,18 @@ def tearDown(self): def test_installer_type(self): """Test installer type property.""" self.assertEqual( - self.installer.installer_type, "docker", - f"Installer type mismatch: expected 'docker', got '{self.installer.installer_type}'" + self.installer.installer_type, + "docker", + f"Installer type mismatch: expected 'docker', got '{self.installer.installer_type}'", ) @regression_test def test_supported_schemes(self): """Test supported schemes property.""" self.assertEqual( - self.installer.supported_schemes, ["dockerhub"], - f"Supported schemes mismatch: expected ['dockerhub'], got {self.installer.supported_schemes}" + self.installer.supported_schemes, + ["dockerhub"], + f"Supported schemes mismatch: expected ['dockerhub'], got {self.installer.supported_schemes}", ) @regression_test @@ -87,12 +95,12 @@ def test_can_install_valid_dependency(self): "name": "nginx", "version_constraint": ">=1.25.0", "type": "docker", - "registry": "dockerhub" + "registry": "dockerhub", } - with patch.object(self.installer, '_is_docker_available', return_value=True): + with patch.object(self.installer, "_is_docker_available", return_value=True): self.assertTrue( self.installer.can_install(dependency), - f"can_install should return True for valid dependency: {dependency}" + f"can_install should return True for valid dependency: {dependency}", ) @regression_test @@ -101,26 +109,29 @@ def test_can_install_wrong_type(self): dependency = { "name": "requests", "version_constraint": ">=2.0.0", - "type": "python" + "type": "python", } self.assertFalse( self.installer.can_install(dependency), - f"can_install should return False for non-docker dependency: {dependency}" + f"can_install should return False for non-docker dependency: {dependency}", ) @integration_test(scope="service") - @unittest.skipUnless(DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}") + @unittest.skipUnless( + DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, + f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}", + ) def test_can_install_docker_unavailable(self): """Test can_install when Docker daemon is unavailable.""" dependency = { "name": "nginx", "version_constraint": ">=1.25.0", - "type": "docker" + "type": "docker", } - with patch.object(self.installer, '_is_docker_available', return_value=False): + with patch.object(self.installer, "_is_docker_available", return_value=False): self.assertFalse( self.installer.can_install(dependency), - f"can_install should return False when Docker is unavailable for dependency: {dependency}" + f"can_install should return False when Docker is unavailable for dependency: {dependency}", ) @regression_test @@ -130,35 +141,29 @@ def test_validate_dependency_valid(self): "name": "nginx", "version_constraint": ">=1.25.0", "type": "docker", - "registry": "dockerhub" + "registry": "dockerhub", } self.assertTrue( self.installer.validate_dependency(dependency), - f"validate_dependency should return True for valid dependency: {dependency}" + f"validate_dependency should return True for valid dependency: {dependency}", ) @regression_test def test_validate_dependency_missing_name(self): """Test validate_dependency with missing name field.""" - dependency = { - "version_constraint": ">=1.25.0", - "type": "docker" - } + dependency = {"version_constraint": ">=1.25.0", "type": "docker"} self.assertFalse( self.installer.validate_dependency(dependency), - f"validate_dependency should return False when 'name' is missing: {dependency}" + f"validate_dependency should return False when 'name' is missing: {dependency}", ) @regression_test def test_validate_dependency_missing_version_constraint(self): """Test validate_dependency with missing version_constraint field.""" - dependency = { - "name": "nginx", - "type": "docker" - } + dependency = {"name": "nginx", "type": "docker"} self.assertFalse( self.installer.validate_dependency(dependency), - f"validate_dependency should return False when 'version_constraint' is missing: {dependency}" + f"validate_dependency should return False when 'version_constraint' is missing: {dependency}", ) @regression_test @@ -167,11 +172,11 @@ def test_validate_dependency_invalid_type(self): dependency = { "name": "nginx", "version_constraint": ">=1.25.0", - "type": "python" + "type": "python", } self.assertFalse( self.installer.validate_dependency(dependency), - f"validate_dependency should return False for invalid type: {dependency}" + f"validate_dependency should return False for invalid type: {dependency}", ) @regression_test @@ -181,11 +186,11 @@ def test_validate_dependency_invalid_registry(self): "name": "nginx", "version_constraint": ">=1.25.0", "type": "docker", - "registry": "gcr.io" + "registry": "gcr.io", } self.assertFalse( self.installer.validate_dependency(dependency), - f"validate_dependency should return False for unsupported registry: {dependency}" + f"validate_dependency should return False for unsupported registry: {dependency}", ) @regression_test @@ -194,11 +199,11 @@ def test_validate_dependency_invalid_version_constraint(self): dependency = { "name": "nginx", "version_constraint": "invalid_version", - "type": "docker" + "type": "docker", } self.assertFalse( self.installer.validate_dependency(dependency), - f"validate_dependency should return False for invalid version_constraint: {dependency}" + f"validate_dependency should return False for invalid version_constraint: {dependency}", ) @regression_test @@ -206,19 +211,19 @@ def test_version_constraint_validation(self): """Test various version constraint formats.""" valid_constraints = [ "1.25.0", - ">=1.25.0", # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. - "==1.25.0", # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. - "<=2.0.0", # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. - #"!=1.24.0", # Docker works with tags and not version constraint, so this one is really irrelevant + ">=1.25.0", # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. + "==1.25.0", # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. + "<=2.0.0", # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. + # "!=1.24.0", # Docker works with tags and not version constraint, so this one is really irrelevant "latest", "1.25", - "1" + "1", ] for constraint in valid_constraints: with self.subTest(constraint=constraint): self.assertTrue( self.installer._validate_version_constraint(constraint), - f"_validate_version_constraint should return True for valid constraint: '{constraint}'" + f"_validate_version_constraint should return True for valid constraint: '{constraint}'", ) @regression_test @@ -227,17 +232,27 @@ def test_resolve_docker_tag(self): test_cases = [ ("latest", "latest"), ("1.25.0", "1.25.0"), - ("==1.25.0", "1.25.0"), # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. - (">=1.25.0", "1.25.0"), # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. - ("<=1.25.0", "1.25.0"), # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. - #("!=1.24.0", "latest"), # Docker works with tags and not version constraint, so this one is really irrelevant + ( + "==1.25.0", + "1.25.0", + ), # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. + ( + ">=1.25.0", + "1.25.0", + ), # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. + ( + "<=1.25.0", + "1.25.0", + ), # Theoretically valid, but Docker works with tags and not version constraints. This is just to ensure the method can handle it. + # ("!=1.24.0", "latest"), # Docker works with tags and not version constraint, so this one is really irrelevant ] for constraint, expected in test_cases: with self.subTest(constraint=constraint): result = self.installer._resolve_docker_tag(constraint) self.assertEqual( - result, expected, - f"_resolve_docker_tag('{constraint}') returned '{result}', expected '{expected}'" + result, + expected, + f"_resolve_docker_tag('{constraint}') returned '{result}', expected '{expected}'", ) @regression_test @@ -247,29 +262,39 @@ def test_install_simulation_mode(self): "name": "nginx", "version_constraint": ">=1.25.0", "type": "docker", - "registry": "dockerhub" + "registry": "dockerhub", } simulation_context = DummyContext(simulation_mode=True) progress_calls = [] + def progress_callback(message, percent, status): progress_calls.append((message, percent, status)) - result = self.installer.install(dependency, simulation_context, progress_callback) + + result = self.installer.install( + dependency, simulation_context, progress_callback + ) self.assertEqual( - result.status, InstallationStatus.COMPLETED, - f"Simulation install should return COMPLETED, got {result.status} with message: {result.metadata["message"]}" + result.status, + InstallationStatus.COMPLETED, + f"Simulation install should return COMPLETED, got {result.status} with message: {result.metadata['message']}", ) self.assertIn( - "Simulated installation", result.metadata["message"], - f"Simulation install message should mention 'Simulated installation', got: {result.metadata["message"]}" + "Simulated installation", + result.metadata["message"], + f"Simulation install message should mention 'Simulated installation', got: {result.metadata['message']}", ) self.assertEqual( - len(progress_calls), 2, - f"Simulation install should call progress_callback twice (start and completion), got {len(progress_calls)} calls: {progress_calls}" + len(progress_calls), + 2, + f"Simulation install should call progress_callback twice (start and completion), got {len(progress_calls)} calls: {progress_calls}", ) @regression_test - @unittest.skipUnless(DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}") - @patch('hatch.installers.docker_installer.docker') + @unittest.skipUnless( + DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, + f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}", + ) + @patch("hatch.installers.docker_installer.docker") def test_install_success(self, mock_docker): """Test successful Docker image installation.""" mock_client = Mock() @@ -280,37 +305,43 @@ def test_install_success(self, mock_docker): "name": "nginx", "version_constraint": "1.25.0", "type": "docker", - "registry": "dockerhub" + "registry": "dockerhub", } progress_calls = [] + def progress_callback(message, percent, status): progress_calls.append((message, percent, status)) + result = self.installer.install(dependency, self.context, progress_callback) self.assertEqual( - result.status, InstallationStatus.COMPLETED, - f"Install should return COMPLETED, got {result.status} with message: {result.metadata["message"]}" + result.status, + InstallationStatus.COMPLETED, + f"Install should return COMPLETED, got {result.status} with message: {result.metadata['message']}", ) mock_client.images.pull.assert_called_once_with("nginx:1.25.0") self.assertGreater( - len(progress_calls), 0, - f"Install should call progress_callback at least once, got {len(progress_calls)} calls: {progress_calls}" + len(progress_calls), + 0, + f"Install should call progress_callback at least once, got {len(progress_calls)} calls: {progress_calls}", ) @regression_test - @unittest.skipUnless(DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}") - @patch('hatch.installers.docker_installer.docker') + @unittest.skipUnless( + DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, + f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}", + ) + @patch("hatch.installers.docker_installer.docker") def test_install_failure(self, mock_docker): """Test Docker installation failure.""" mock_client = Mock() mock_docker.from_env.return_value = mock_client mock_client.ping.return_value = True mock_client.images.pull.side_effect = Exception("Network error") - dependency = { - "name": "nginx", - "version_constraint": "1.25.0", - "type": "docker" - } - with self.assertRaises(InstallationError, msg=f"Install should raise InstallationError on failure for dependency: {dependency}"): + dependency = {"name": "nginx", "version_constraint": "1.25.0", "type": "docker"} + with self.assertRaises( + InstallationError, + msg=f"Install should raise InstallationError on failure for dependency: {dependency}", + ): self.installer.install(dependency, self.context) @regression_test @@ -319,14 +350,20 @@ def test_install_invalid_dependency(self): dependency = { "name": "nginx", # Missing version_constraint - "type": "docker" + "type": "docker", } - with self.assertRaises(InstallationError, msg=f"Install should raise InstallationError for invalid dependency: {dependency}"): + with self.assertRaises( + InstallationError, + msg=f"Install should raise InstallationError for invalid dependency: {dependency}", + ): self.installer.install(dependency, self.context) @regression_test - @unittest.skipUnless(DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}") - @patch('hatch.installers.docker_installer.docker') + @unittest.skipUnless( + DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, + f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}", + ) + @patch("hatch.installers.docker_installer.docker") def test_uninstall_success(self, mock_docker): """Test successful Docker image uninstallation.""" mock_client = Mock() @@ -338,12 +375,13 @@ def test_uninstall_success(self, mock_docker): "name": "nginx", "version_constraint": "1.25.0", "type": "docker", - "registry": "dockerhub" + "registry": "dockerhub", } result = self.installer.uninstall(dependency, self.context) self.assertEqual( - result.status, InstallationStatus.COMPLETED, - f"Uninstall should return COMPLETED, got {result.status} with message: {result.metadata["message"]}" + result.status, + InstallationStatus.COMPLETED, + f"Uninstall should return COMPLETED, got {result.status} with message: {result.metadata['message']}", ) mock_client.images.remove.assert_called_once_with("nginx:1.25.0", force=False) @@ -354,49 +392,52 @@ def test_uninstall_simulation_mode(self): "name": "nginx", "version_constraint": "1.25.0", "type": "docker", - "registry": "dockerhub" + "registry": "dockerhub", } simulation_context = DummyContext(simulation_mode=True) result = self.installer.uninstall(dependency, simulation_context) self.assertEqual( - result.status, InstallationStatus.COMPLETED, - f"Simulation uninstall should return COMPLETED, got {result.status} with message: {result.metadata["message"]}" + result.status, + InstallationStatus.COMPLETED, + f"Simulation uninstall should return COMPLETED, got {result.status} with message: {result.metadata['message']}", ) self.assertIn( - "Simulated removal", result.metadata["message"], - f"Simulation uninstall message should mention 'Simulated removal', got: {result.metadata["message"]}" + "Simulated removal", + result.metadata["message"], + f"Simulation uninstall message should mention 'Simulated removal', got: {result.metadata['message']}", ) @regression_test def test_get_installation_info_docker_unavailable(self): """Test get_installation_info when Docker is unavailable.""" - dependency = { - "name": "nginx", - "version_constraint": "1.25.0", - "type": "docker" - } - with patch.object(self.installer, '_is_docker_available', return_value=False): + dependency = {"name": "nginx", "version_constraint": "1.25.0", "type": "docker"} + with patch.object(self.installer, "_is_docker_available", return_value=False): info = self.installer.get_installation_info(dependency, self.context) self.assertEqual( - info["installer_type"], "docker", - f"get_installation_info: installer_type should be 'docker', got {info['installer_type']}" + info["installer_type"], + "docker", + f"get_installation_info: installer_type should be 'docker', got {info['installer_type']}", ) self.assertEqual( - info["dependency_name"], "nginx", - f"get_installation_info: dependency_name should be 'nginx', got {info['dependency_name']}" + info["dependency_name"], + "nginx", + f"get_installation_info: dependency_name should be 'nginx', got {info['dependency_name']}", ) self.assertFalse( info["docker_available"], - f"get_installation_info: docker_available should be False, got {info['docker_available']}" + f"get_installation_info: docker_available should be False, got {info['docker_available']}", ) self.assertFalse( info["can_install"], - f"get_installation_info: can_install should be False, got {info['can_install']}" + f"get_installation_info: can_install should be False, got {info['can_install']}", ) @regression_test - @unittest.skipUnless(DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}") - @patch('hatch.installers.docker_installer.docker') + @unittest.skipUnless( + DOCKER_AVAILABLE and DOCKER_DAEMON_AVAILABLE, + f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}", + ) + @patch("hatch.installers.docker_installer.docker") def test_get_installation_info_image_installed(self, mock_docker): """Test get_installation_info for installed image.""" mock_client = Mock() @@ -406,119 +447,127 @@ def test_get_installation_info_image_installed(self, mock_docker): mock_image.id = "sha256:abc123" mock_image.tags = ["nginx:1.25.0"] mock_client.images.get.return_value = mock_image - dependency = { - "name": "nginx", - "version_constraint": "1.25.0", - "type": "docker" - } - - with patch.object(self.installer, '_is_docker_available', return_value=True): + dependency = {"name": "nginx", "version_constraint": "1.25.0", "type": "docker"} + + with patch.object(self.installer, "_is_docker_available", return_value=True): info = self.installer.get_installation_info(dependency, self.context) - + self.assertTrue(info["docker_available"]) self.assertTrue(info["installed"]) self.assertEqual(info["image_id"], "sha256:abc123") class TestDockerInstallerIntegration(unittest.TestCase): - """Integration tests for DockerInstaller using real Docker operations.""" + """Integration tests for DockerInstaller with mocked Docker operations.""" def setUp(self): """Set up integration test fixtures.""" - if not DOCKER_AVAILABLE or not DOCKER_DAEMON_AVAILABLE: - self.skipTest(f"Docker library not available or Docker daemon not available: library={DOCKER_AVAILABLE}, daemon={DOCKER_DAEMON_AVAILABLE}") - self.installer = DockerInstaller() self.temp_dir = tempfile.mkdtemp() self.context = DummyContext(env_path=Path(self.temp_dir)) - - # Check if Docker daemon is actually available - if not self.installer._is_docker_available(): - self.skipTest("Docker daemon not available") def tearDown(self): """Clean up integration test fixtures.""" - if hasattr(self, 'temp_dir'): + if hasattr(self, "temp_dir"): shutil.rmtree(self.temp_dir) @integration_test(scope="service") - @slow_test - def test_docker_daemon_availability(self): + @patch.object(DockerInstaller, "_is_docker_available", return_value=True) + def test_docker_daemon_availability(self, mock_available): """Test Docker daemon availability detection.""" self.assertTrue(self.installer._is_docker_available()) + mock_available.assert_called() @integration_test(scope="service") - @slow_test - def test_install_and_uninstall_small_image(self): - """Test installing and uninstalling a small Docker image. + @patch.object(DockerInstaller, "_is_docker_available", return_value=True) + @patch.object(DockerInstaller, "_get_docker_client") + def test_install_and_uninstall_small_image(self, mock_get_client, mock_available): + """Test installing and uninstalling a small Docker image (mocked). - This test uses the alpine image which is very small (~5MB) to minimize - download time and resource usage in CI environments. + This test verifies the install/uninstall flow with mocked Docker client + operations instead of real Docker pull/rm. """ + # Set up mock Docker client + mock_client = Mock() + mock_client.ping.return_value = True + mock_client.images.pull.return_value = Mock() + mock_image = Mock() + mock_image.id = "sha256:mock123" + mock_image.tags = ["alpine:latest"] + mock_client.images.get.return_value = mock_image + mock_client.containers.list.return_value = [] + mock_client.images.remove.return_value = None + mock_get_client.return_value = mock_client + dependency = { "name": "alpine", "version_constraint": "latest", "type": "docker", - "registry": "dockerhub" + "registry": "dockerhub", } - + progress_events = [] - + def progress_callback(message, percent, status): progress_events.append((message, percent, status)) - - try: - # Test installation - install_result = self.installer.install(dependency, self.context, progress_callback) - self.assertEqual(install_result.status, InstallationStatus.COMPLETED) - self.assertGreater(len(progress_events), 0) - - # Verify image is installed - info = self.installer.get_installation_info(dependency, self.context) - self.assertTrue(info.get("installed", False)) - - # Test uninstallation - progress_events.clear() - uninstall_result = self.installer.uninstall(dependency, self.context, progress_callback) - self.assertEqual(uninstall_result.status, InstallationStatus.COMPLETED) - - except InstallationError as e: - if e.error_code == "DOCKER_DAEMON_NOT_AVAILABLE": - self.skipTest(f"Integration test failed due to Docker/network issues: {e}") - else: - raise e + + # Test installation + install_result = self.installer.install( + dependency, self.context, progress_callback + ) + self.assertEqual(install_result.status, InstallationStatus.COMPLETED) + self.assertGreater(len(progress_events), 0) + mock_client.images.pull.assert_called_once_with("alpine:latest") + + # Verify image is installed + info = self.installer.get_installation_info(dependency, self.context) + self.assertTrue(info.get("installed", False)) + + # Test uninstallation + progress_events.clear() + uninstall_result = self.installer.uninstall( + dependency, self.context, progress_callback + ) + self.assertEqual(uninstall_result.status, InstallationStatus.COMPLETED) + mock_client.images.remove.assert_called_once_with("alpine:latest", force=False) @integration_test(scope="service") - @slow_test - def test_docker_dep_pkg_integration(self): - """Test integration with docker_dep_pkg dummy package. + @patch.object(DockerInstaller, "_is_docker_available", return_value=True) + @patch.object(DockerInstaller, "_get_docker_client") + def test_docker_dep_pkg_integration(self, mock_get_client, mock_available): + """Test integration with docker_dep_pkg dummy package (mocked). This test validates the installer works with the real dependency format - from the Hatching-Dev docker_dep_pkg. + from the Hatching-Dev docker_dep_pkg using mocked Docker operations. """ + # Set up mock Docker client + mock_client = Mock() + mock_client.ping.return_value = True + mock_image = Mock() + mock_image.id = "sha256:mock456" + mock_image.tags = ["nginx:1.25.0"] + mock_client.images.get.return_value = mock_image + mock_get_client.return_value = mock_client + # Dependency based on docker_dep_pkg/hatch_metadata.json dependency = { "name": "nginx", "version_constraint": ">=1.25.0", "type": "docker", - "registry": "dockerhub" + "registry": "dockerhub", } - - try: - # Test validation - self.assertTrue(self.installer.validate_dependency(dependency)) - - # Test can_install - self.assertTrue(self.installer.can_install(dependency)) - - # Test installation info - info = self.installer.get_installation_info(dependency, self.context) - self.assertEqual(info["installer_type"], "docker") - self.assertEqual(info["dependency_name"], "nginx") - - except Exception as e: - self.skipTest(f"Docker dep pkg integration test failed: {e}") + + # Test validation + self.assertTrue(self.installer.validate_dependency(dependency)) + + # Test can_install + self.assertTrue(self.installer.can_install(dependency)) + + # Test installation info + info = self.installer.get_installation_info(dependency, self.context) + self.assertEqual(info["installer_type"], "docker") + self.assertEqual(info["dependency_name"], "nginx") if __name__ == "__main__": - unittest.main() \ No newline at end of file + unittest.main() diff --git a/tests/test_env_manip.py b/tests/test_env_manip.py index fca4276..ab336a7 100644 --- a/tests/test_env_manip.py +++ b/tests/test_env_manip.py @@ -1,4 +1,3 @@ -import sys import json import unittest import logging @@ -9,49 +8,62 @@ from datetime import datetime from unittest.mock import patch -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test, integration_test # Import path management removed - using test_data_utils for test dependencies from hatch.environment_manager import HatchEnvironmentManager -from hatch.installers.docker_installer import DOCKER_DAEMON_AVAILABLE +from hatch.python_environment_manager import PythonEnvironmentManager +from hatch.installers.docker_installer import DockerInstaller +from hatch.installers.system_installer import SystemInstaller # Configure logging logging.basicConfig( - level=logging.INFO, - format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' + level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s" ) logger = logging.getLogger("hatch.environment_tests") + class PackageEnvironmentTests(unittest.TestCase): """Tests for the package environment management functionality.""" - + def setUp(self): """Set up test environment before each test.""" # Create a temporary directory for test environments self.temp_dir = tempfile.mkdtemp() - - # Path to Hatching-Dev packages + + # Path to Hatching-Dev packages (used by some integration-style tests) self.hatch_dev_path = Path(__file__).parent.parent.parent / "Hatching-Dev" - self.assertTrue(self.hatch_dev_path.exists(), - f"Hatching-Dev directory not found at {self.hatch_dev_path}") - - # Create a sample registry that includes Hatching-Dev packages + + # Create a sample registry that includes test packages self._create_sample_registry() - + # Override environment paths to use our test directory env_dir = Path(self.temp_dir) / "envs" env_dir.mkdir(exist_ok=True) - + + # Patch slow operations before creating HatchEnvironmentManager: + # 1. _detect_conda_mamba: prevents subprocess calls to find conda/mamba + # 2. _install_hatch_mcp_server: prevents real pip install from GitHub + self._patcher_detect = patch.object( + PythonEnvironmentManager, "_detect_conda_mamba" + ) + self._patcher_install_mcp = patch.object( + HatchEnvironmentManager, "_install_hatch_mcp_server" + ) + self._mock_detect = self._patcher_detect.start() + self._mock_install_mcp = self._patcher_install_mcp.start() + # Create environment manager for testing with isolated test directories self.env_manager = HatchEnvironmentManager( environments_dir=env_dir, simulation_mode=True, - local_registry_cache_path=self.registry_path) - + local_registry_cache_path=self.registry_path, + ) + # Reload environments to ensure clean state self.env_manager.reload_environments() - + def _create_sample_registry(self): """Create a sample registry with Hatching-Dev packages using real metadata.""" now = datetime.now().isoformat() @@ -63,21 +75,24 @@ def _create_sample_registry(self): "name": "test-repo", "url": f"file://{self.hatch_dev_path}", "last_indexed": now, - "packages": [] + "packages": [], } ], - "stats": { - "total_packages": 0, - "total_versions": 0 - } + "stats": {"total_packages": 0, "total_versions": 0}, } # Use self-contained test packages instead of external Hatching-Dev from test_data_utils import TestDataLoader + test_loader = TestDataLoader() pkg_names = [ - "base_pkg", "utility_pkg", "python_dep_pkg", - "circular_dep_pkg", "circular_dep_pkg_b", "complex_dep_pkg", "simple_dep_pkg" + "base_pkg", + "utility_pkg", + "python_dep_pkg", + "circular_dep_pkg", + "circular_dep_pkg_b", + "complex_dep_pkg", + "simple_dep_pkg", ] for pkg_name in pkg_names: # Map to self-contained package locations @@ -93,7 +108,7 @@ def _create_sample_registry(self): metadata_path = pkg_path / "hatch_metadata.json" if metadata_path.exists(): try: - with open(metadata_path, 'r') as f: + with open(metadata_path, "r") as f: metadata = json.load(f) pkg_entry = { "name": metadata.get("name", pkg_name), @@ -105,59 +120,84 @@ def _create_sample_registry(self): "version": metadata.get("version", "1.0.0"), "release_uri": f"file://{pkg_path}", "author": { - "GitHubID": metadata.get("author", {}).get("name", "test_user"), - "email": metadata.get("author", {}).get("email", "test@example.com") + "GitHubID": metadata.get("author", {}).get( + "name", "test_user" + ), + "email": metadata.get("author", {}).get( + "email", "test@example.com" + ), }, "added_date": now, "hatch_dependencies_added": [ { "name": dep["name"], - "version_constraint": dep.get("version_constraint", "") - } for dep in metadata.get("dependencies", {}).get("hatch", []) + "version_constraint": dep.get( + "version_constraint", "" + ), + } + for dep in metadata.get("dependencies", {}).get( + "hatch", [] + ) ], "python_dependencies_added": [ { "name": dep["name"], - "version_constraint": dep.get("version_constraint", ""), - "package_manager": dep.get("package_manager", "pip") - } for dep in metadata.get("dependencies", {}).get("python", []) + "version_constraint": dep.get( + "version_constraint", "" + ), + "package_manager": dep.get( + "package_manager", "pip" + ), + } + for dep in metadata.get("dependencies", {}).get( + "python", [] + ) ], "hatch_dependencies_removed": [], "hatch_dependencies_modified": [], "python_dependencies_removed": [], "python_dependencies_modified": [], - "compatibility_changes": {} + "compatibility_changes": {}, } - ] + ], } registry["repositories"][0]["packages"].append(pkg_entry) except Exception as e: logger.error(f"Failed to load metadata for {pkg_name}: {e}") raise e # Update stats - registry["stats"]["total_packages"] = len(registry["repositories"][0]["packages"]) - registry["stats"]["total_versions"] = sum(len(pkg["versions"]) for pkg in registry["repositories"][0]["packages"]) + registry["stats"]["total_packages"] = len( + registry["repositories"][0]["packages"] + ) + registry["stats"]["total_versions"] = sum( + len(pkg["versions"]) for pkg in registry["repositories"][0]["packages"] + ) registry_dir = Path(self.temp_dir) / "registry" registry_dir.mkdir(parents=True, exist_ok=True) self.registry_path = registry_dir / "hatch_packages_registry.json" with open(self.registry_path, "w") as f: json.dump(registry, f, indent=2) logger.info(f"Sample registry created at {self.registry_path}") - + def tearDown(self): """Clean up test environment after each test.""" + # Stop patchers + self._patcher_detect.stop() + self._patcher_install_mcp.stop() # Remove temporary directory shutil.rmtree(self.temp_dir) - + @regression_test - @slow_test def test_create_environment(self): """Test creating an environment.""" result = self.env_manager.create_environment("test_env", "Test environment") self.assertTrue(result, "Failed to create environment") # Verify environment exists - self.assertTrue(self.env_manager.environment_exists("test_env"), "Environment doesn't exist after creation") + self.assertTrue( + self.env_manager.environment_exists("test_env"), + "Environment doesn't exist after creation", + ) # Verify environment data env_data = self.env_manager.get_environments().get("test_env") @@ -169,7 +209,6 @@ def test_create_environment(self): self.assertEqual(len(env_data["packages"]), 0) @regression_test - @slow_test def test_remove_environment(self): """Test removing an environment.""" # First create an environment @@ -179,12 +218,14 @@ def test_remove_environment(self): # Then remove it result = self.env_manager.remove_environment("test_env") self.assertTrue(result, "Failed to remove environment") - + # Verify environment no longer exists - self.assertFalse(self.env_manager.environment_exists("test_env"), "Environment still exists after removal") - + self.assertFalse( + self.env_manager.environment_exists("test_env"), + "Environment still exists after removal", + ) + @regression_test - @slow_test def test_set_current_environment(self): """Test setting the current environment.""" # First create an environment @@ -196,10 +237,11 @@ def test_set_current_environment(self): # Verify it's the current environment current_env = self.env_manager.get_current_environment() - self.assertEqual(current_env, "test_env", "Current environment not set correctly") + self.assertEqual( + current_env, "test_env", "Current environment not set correctly" + ) @regression_test - @slow_test def test_add_local_package(self): """Test adding a local package to an environment.""" # Create an environment @@ -208,6 +250,7 @@ def test_add_local_package(self): # Use base_pkg from self-contained test data from test_data_utils import TestDataLoader + test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / "base_pkg" self.assertTrue(pkg_path.exists(), f"Test package not found: {pkg_path}") @@ -216,7 +259,7 @@ def test_add_local_package(self): result = self.env_manager.add_package_to_environment( str(pkg_path), # Convert to string to handle Path objects "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) self.assertTrue(result, "Failed to add local package to environment") @@ -235,68 +278,80 @@ def test_add_local_package(self): self.assertIn("source", pkg_data, "Package data missing source") @regression_test - @slow_test def test_add_package_with_dependencies(self): """Test adding a package with dependencies to an environment.""" # Create an environment - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) self.env_manager.set_current_environment("test_env") # First add the base package that is a dependency from test_data_utils import TestDataLoader + test_loader = TestDataLoader() base_pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - self.assertTrue(base_pkg_path.exists(), f"Base package not found: {base_pkg_path}") + self.assertTrue( + base_pkg_path.exists(), f"Base package not found: {base_pkg_path}" + ) result = self.env_manager.add_package_to_environment( str(base_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) self.assertTrue(result, "Failed to add base package to environment") # Then add the package with dependencies pkg_path = test_loader.packages_dir / "dependencies" / "simple_dep_pkg" self.assertTrue(pkg_path.exists(), f"Dependent package not found: {pkg_path}") - + # Add package to environment result = self.env_manager.add_package_to_environment( - str(pkg_path), - "test_env", - auto_approve=True # Auto-approve for testing + str(pkg_path), "test_env", auto_approve=True # Auto-approve for testing ) - + self.assertTrue(result, "Failed to add package with dependencies") - + # Verify both packages are in the environment env_data = self.env_manager.get_environments().get("test_env") self.assertIsNotNone(env_data, "Environment data not found") - + packages = env_data.get("packages", []) self.assertEqual(len(packages), 2, "Not all packages were added to environment") - + # Check that both packages are in the environment data package_names = [pkg["name"] for pkg in packages] - self.assertIn("base_pkg", package_names, "Base package missing from environment") - self.assertIn("simple_dep_pkg", package_names, "Dependent package missing from environment") - + self.assertIn( + "base_pkg", package_names, "Base package missing from environment" + ) + self.assertIn( + "simple_dep_pkg", + package_names, + "Dependent package missing from environment", + ) + @regression_test - @slow_test def test_add_package_with_some_dependencies_already_present(self): """Test adding a package where some dependencies are already present and others are not.""" # Create an environment - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) self.env_manager.set_current_environment("test_env") # First add only one of the dependencies that complex_dep_pkg needs from test_data_utils import TestDataLoader + test_loader = TestDataLoader() base_pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - self.assertTrue(base_pkg_path.exists(), f"Base package not found: {base_pkg_path}") + self.assertTrue( + base_pkg_path.exists(), f"Base package not found: {base_pkg_path}" + ) result = self.env_manager.add_package_to_environment( str(base_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) self.assertTrue(result, "Failed to add base package to environment") @@ -305,16 +360,18 @@ def test_add_package_with_some_dependencies_already_present(self): packages = env_data.get("packages", []) self.assertEqual(len(packages), 1, "Base package not added correctly") self.assertEqual(packages[0]["name"], "base_pkg", "Wrong package added") - + # Now add complex_dep_pkg which depends on base_pkg, utility_pkg # base_pkg should be satisfied, utility_pkg should need installation complex_pkg_path = test_loader.packages_dir / "dependencies" / "complex_dep_pkg" - self.assertTrue(complex_pkg_path.exists(), f"Complex package not found: {complex_pkg_path}") + self.assertTrue( + complex_pkg_path.exists(), f"Complex package not found: {complex_pkg_path}" + ) result = self.env_manager.add_package_to_environment( str(complex_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) self.assertTrue(result, "Failed to add package with mixed dependency states") @@ -326,27 +383,33 @@ def test_add_package_with_some_dependencies_already_present(self): # Should have base_pkg (already present), utility_pkg, and complex_dep_pkg expected_packages = ["base_pkg", "utility_pkg", "complex_dep_pkg"] package_names = [pkg["name"] for pkg in packages] - + for pkg_name in expected_packages: - self.assertIn(pkg_name, package_names, f"Package {pkg_name} missing from environment") - + self.assertIn( + pkg_name, package_names, f"Package {pkg_name} missing from environment" + ) + @regression_test - @slow_test def test_add_package_with_all_dependencies_already_present(self): """Test adding a package where all dependencies are already present.""" # Create an environment - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) self.env_manager.set_current_environment("test_env") # First add all dependencies that simple_dep_pkg needs from test_data_utils import TestDataLoader + test_loader = TestDataLoader() base_pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - self.assertTrue(base_pkg_path.exists(), f"Base package not found: {base_pkg_path}") + self.assertTrue( + base_pkg_path.exists(), f"Base package not found: {base_pkg_path}" + ) result = self.env_manager.add_package_to_environment( str(base_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) self.assertTrue(result, "Failed to add base package to environment") @@ -357,12 +420,14 @@ def test_add_package_with_all_dependencies_already_present(self): # Now add simple_dep_pkg which only depends on base_pkg (which is already present) simple_pkg_path = test_loader.packages_dir / "dependencies" / "simple_dep_pkg" - self.assertTrue(simple_pkg_path.exists(), f"Simple package not found: {simple_pkg_path}") + self.assertTrue( + simple_pkg_path.exists(), f"Simple package not found: {simple_pkg_path}" + ) result = self.env_manager.add_package_to_environment( str(simple_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) self.assertTrue(result, "Failed to add package with all dependencies satisfied") @@ -370,75 +435,120 @@ def test_add_package_with_all_dependencies_already_present(self): # Verify both packages are in the environment - no new dependencies should be added env_data = self.env_manager.get_environments().get("test_env") packages = env_data.get("packages", []) - + # Should have base_pkg (already present) and simple_dep_pkg (newly added) expected_packages = ["base_pkg", "simple_dep_pkg"] package_names = [pkg["name"] for pkg in packages] - self.assertEqual(len(packages), 2, "Unexpected number of packages in environment") + self.assertEqual( + len(packages), 2, "Unexpected number of packages in environment" + ) for pkg_name in expected_packages: - self.assertIn(pkg_name, package_names, f"Package {pkg_name} missing from environment") - + self.assertIn( + pkg_name, package_names, f"Package {pkg_name} missing from environment" + ) + @regression_test - @slow_test def test_add_package_with_version_constraint_satisfaction(self): """Test adding a package with version constraints where dependencies are satisfied.""" # Create an environment - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) self.env_manager.set_current_environment("test_env") # Add base_pkg with a specific version from test_data_utils import TestDataLoader + test_loader = TestDataLoader() base_pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - self.assertTrue(base_pkg_path.exists(), f"Base package not found: {base_pkg_path}") + self.assertTrue( + base_pkg_path.exists(), f"Base package not found: {base_pkg_path}" + ) result = self.env_manager.add_package_to_environment( str(base_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) self.assertTrue(result, "Failed to add base package to environment") # Look for a package that has version constraints to test against # For now, we'll simulate this by trying to add another package that depends on base_pkg simple_pkg_path = test_loader.packages_dir / "dependencies" / "simple_dep_pkg" - self.assertTrue(simple_pkg_path.exists(), f"Simple package not found: {simple_pkg_path}") + self.assertTrue( + simple_pkg_path.exists(), f"Simple package not found: {simple_pkg_path}" + ) result = self.env_manager.add_package_to_environment( str(simple_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) - self.assertTrue(result, "Failed to add package with version constraint dependencies") + self.assertTrue( + result, "Failed to add package with version constraint dependencies" + ) # Verify packages are correctly installed env_data = self.env_manager.get_environments().get("test_env") packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] - self.assertIn("base_pkg", package_names, "Base package missing from environment") - self.assertIn("simple_dep_pkg", package_names, "Dependent package missing from environment") + self.assertIn( + "base_pkg", package_names, "Base package missing from environment" + ) + self.assertIn( + "simple_dep_pkg", + package_names, + "Dependent package missing from environment", + ) @integration_test(scope="component") - @slow_test - def test_add_package_with_mixed_dependency_types(self): + @patch.object(PythonEnvironmentManager, "get_environment_info") + @patch.object( + PythonEnvironmentManager, "create_python_environment", return_value=True + ) + @patch.object(PythonEnvironmentManager, "is_available", return_value=True) + def test_add_package_with_mixed_dependency_types( + self, mock_is_available, mock_create_env, mock_get_info + ): """Test adding a package with mixed hatch and python dependencies.""" + # Mock get_environment_info to return fake python env data with "requests" + mock_get_info.return_value = { + "conda_env_name": "hatch_test_env", + "python_executable": "/usr/bin/python3", + "python_version": "3.12", + "manager": "mamba", + "environment_path": "/fake/path", + "package_count": 3, + "packages": [ + {"name": "numpy", "version": "1.26.0"}, + {"name": "requests", "version": "2.31.0"}, + {"name": "pip", "version": "23.0"}, + ], + } + # Create an environment self.env_manager.create_environment("test_env", "Test environment") self.env_manager.set_current_environment("test_env") # Add a package that has both hatch and python dependencies from test_data_utils import TestDataLoader + test_loader = TestDataLoader() - python_dep_pkg_path = test_loader.packages_dir / "dependencies" / "python_dep_pkg" - self.assertTrue(python_dep_pkg_path.exists(), f"Python dependency package not found: {python_dep_pkg_path}") + python_dep_pkg_path = ( + test_loader.packages_dir / "dependencies" / "python_dep_pkg" + ) + self.assertTrue( + python_dep_pkg_path.exists(), + f"Python dependency package not found: {python_dep_pkg_path}", + ) result = self.env_manager.add_package_to_environment( str(python_dep_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) self.assertTrue(result, "Failed to add package with mixed dependency types") @@ -448,53 +558,84 @@ def test_add_package_with_mixed_dependency_types(self): packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] - self.assertIn("python_dep_pkg", package_names, "Package with mixed dependencies missing from environment") + self.assertIn( + "python_dep_pkg", + package_names, + "Package with mixed dependencies missing from environment", + ) # Now add a package that depends on the python_dep_pkg (should be satisfied) # and also depends on other packages (should need installation) complex_pkg_path = test_loader.packages_dir / "dependencies" / "complex_dep_pkg" - self.assertTrue(complex_pkg_path.exists(), f"Complex package not found: {complex_pkg_path}") - + self.assertTrue( + complex_pkg_path.exists(), f"Complex package not found: {complex_pkg_path}" + ) + result = self.env_manager.add_package_to_environment( str(complex_pkg_path), "test_env", - auto_approve=True # Auto-approve for testing + auto_approve=True, # Auto-approve for testing ) - - self.assertTrue(result, "Failed to add package with mixed satisfied/unsatisfied dependencies") - + + self.assertTrue( + result, + "Failed to add package with mixed satisfied/unsatisfied dependencies", + ) + # Verify all expected packages are present env_data = self.env_manager.get_environments().get("test_env") packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] - + # Should have python_dep_pkg (already present) plus any other dependencies of complex_dep_pkg - self.assertIn("python_dep_pkg", package_names, "Originally installed package missing") - self.assertIn("complex_dep_pkg", package_names, "New package missing from environment") + self.assertIn( + "python_dep_pkg", package_names, "Originally installed package missing" + ) + self.assertIn( + "complex_dep_pkg", package_names, "New package missing from environment" + ) # Python dep package has a dep to request. This should be satisfied in the python environment - python_env_info = self.env_manager.python_env_manager.get_environment_info("test_env") + python_env_info = self.env_manager.python_env_manager.get_environment_info( + "test_env" + ) packages = python_env_info.get("packages", []) self.assertIsNotNone(packages, "Python environment packages not found") self.assertGreater(len(packages), 0, "No packages found in Python environment") package_names = [pkg["name"] for pkg in packages] - self.assertIn("requests", package_names, f"Expected 'requests' package not found in Python environment: {packages}") + self.assertIn( + "requests", + package_names, + f"Expected 'requests' package not found in Python environment: {packages}", + ) @integration_test(scope="system") - @slow_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") - def test_add_package_with_system_dependency(self): + @patch.object(SystemInstaller, "_verify_installation", return_value="7.0.0") + @patch.object(SystemInstaller, "_run_apt_subprocess", return_value=0) + @patch.object(SystemInstaller, "_is_apt_available", return_value=True) + @patch.object(SystemInstaller, "_is_platform_supported", return_value=True) + def test_add_package_with_system_dependency( + self, mock_platform, mock_apt_avail, mock_run, mock_verify + ): """Test adding a package with a system dependency.""" - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) self.env_manager.set_current_environment("test_env") # Add a package that declares a system dependency (e.g., 'curl') - system_dep_pkg_path = self.hatch_dev_path / "system_dep_pkg" - self.assertTrue(system_dep_pkg_path.exists(), f"System dependency package not found: {system_dep_pkg_path}") + from test_data_utils import TestDataLoader + + test_loader = TestDataLoader() + system_dep_pkg_path = ( + test_loader.packages_dir / "dependencies" / "system_dep_pkg" + ) + self.assertTrue( + system_dep_pkg_path.exists(), + f"System dependency package not found: {system_dep_pkg_path}", + ) result = self.env_manager.add_package_to_environment( - str(system_dep_pkg_path), - "test_env", - auto_approve=True + str(system_dep_pkg_path), "test_env", auto_approve=True ) self.assertTrue(result, "Failed to add package with system dependency") @@ -502,24 +643,35 @@ def test_add_package_with_system_dependency(self): env_data = self.env_manager.get_environments().get("test_env") packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] - self.assertIn("system_dep_pkg", package_names, "System dependency package missing from environment") + self.assertIn( + "system_dep_pkg", + package_names, + "System dependency package missing from environment", + ) - # Skip if Docker is not available @integration_test(scope="service") - @slow_test - @unittest.skipUnless(DOCKER_DAEMON_AVAILABLE, "Docker dependency test skipped due to Docker not being available") - def test_add_package_with_docker_dependency(self): + @patch.object(DockerInstaller, "_pull_docker_image") + @patch.object(DockerInstaller, "_is_docker_available", return_value=True) + def test_add_package_with_docker_dependency(self, mock_docker_avail, mock_pull): """Test adding a package with a docker dependency.""" - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) self.env_manager.set_current_environment("test_env") - # Add a package that declares a docker dependency (e.g., 'redis:latest') - docker_dep_pkg_path = self.hatch_dev_path / "docker_dep_pkg" - self.assertTrue(docker_dep_pkg_path.exists(), f"Docker dependency package not found: {docker_dep_pkg_path}") + # Add a package that declares a docker dependency (e.g., 'nginx') + from test_data_utils import TestDataLoader + + test_loader = TestDataLoader() + docker_dep_pkg_path = ( + test_loader.packages_dir / "dependencies" / "docker_dep_pkg" + ) + self.assertTrue( + docker_dep_pkg_path.exists(), + f"Docker dependency package not found: {docker_dep_pkg_path}", + ) result = self.env_manager.add_package_to_environment( - str(docker_dep_pkg_path), - "test_env", - auto_approve=True + str(docker_dep_pkg_path), "test_env", auto_approve=True ) self.assertTrue(result, "Failed to add package with docker dependency") @@ -527,10 +679,13 @@ def test_add_package_with_docker_dependency(self): env_data = self.env_manager.get_environments().get("test_env") packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] - self.assertIn("docker_dep_pkg", package_names, "Docker dependency package missing from environment") + self.assertIn( + "docker_dep_pkg", + package_names, + "Docker dependency package missing from environment", + ) @regression_test - @slow_test def test_create_environment_with_mcp_server_default(self): """Test creating environment with default MCP server installation.""" # Mock the MCP server installation to avoid actual network calls @@ -543,25 +698,31 @@ def mock_install(env_name, tag=None): installed_env = env_name installed_tag = tag # Simulate successful installation - package_git_url = "git+https://github.com/CrackingShells/Hatch-MCP-Server.git" + package_git_url = ( + "git+https://github.com/CrackingShells/Hatch-MCP-Server.git" + ) env_data = self.env_manager._environments[env_name] - env_data["packages"].append({ - "name": f"hatch_mcp_server @ {package_git_url}", - "version": "dev", - "type": "python", - "source": package_git_url, - "installed_at": datetime.now().isoformat() - }) + env_data["packages"].append( + { + "name": f"hatch_mcp_server @ {package_git_url}", + "version": "dev", + "type": "python", + "source": package_git_url, + "installed_at": datetime.now().isoformat(), + } + ) self.env_manager._install_hatch_mcp_server = mock_install try: # Create environment without Python environment but simulate that it has one - success = self.env_manager.create_environment("test_mcp_default", - description="Test MCP default", - create_python_env=False, # Don't create actual Python env - no_hatch_mcp_server=False) - + success = self.env_manager.create_environment( + "test_mcp_default", + description="Test MCP default", + create_python_env=False, # Don't create actual Python env + no_hatch_mcp_server=False, + ) + # Manually set python_env info to simulate having Python support self.env_manager._environments["test_mcp_default"]["python_env"] = { "enabled": True, @@ -569,29 +730,38 @@ def mock_install(env_name, tag=None): "python_executable": "/fake/python", "created_at": datetime.now().isoformat(), "version": "3.11.0", - "manager": "conda" + "manager": "conda", } - + # Now call the MCP installation manually (since we bypassed Python env creation) self.env_manager._install_hatch_mcp_server("test_mcp_default", None) - + self.assertTrue(success, "Environment creation should succeed") - self.assertEqual(installed_env, "test_mcp_default", "MCP server should be installed in correct environment") - self.assertIsNone(installed_tag, "Default installation should use no specific tag") - + self.assertEqual( + installed_env, + "test_mcp_default", + "MCP server should be installed in correct environment", + ) + self.assertIsNone( + installed_tag, "Default installation should use no specific tag" + ) + # Verify MCP server package is in environment env_data = self.env_manager._environments["test_mcp_default"] packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] expected_name = "hatch_mcp_server @ git+https://github.com/CrackingShells/Hatch-MCP-Server.git" - self.assertIn(expected_name, package_names, "MCP server should be installed by default with correct name syntax") - + self.assertIn( + expected_name, + package_names, + "MCP server should be installed by default with correct name syntax", + ) + finally: # Restore original method self.env_manager._install_hatch_mcp_server = original_install @regression_test - @slow_test def test_create_environment_with_mcp_server_opt_out(self): """Test creating environment with MCP server installation opted out.""" # Mock the MCP server installation to track calls @@ -606,10 +776,12 @@ def mock_install(env_name, tag=None): try: # Create environment without Python environment, MCP server opted out - success = self.env_manager.create_environment("test_mcp_opt_out", - description="Test MCP opt out", - create_python_env=False, # Don't create actual Python env - no_hatch_mcp_server=True) + success = self.env_manager.create_environment( + "test_mcp_opt_out", + description="Test MCP opt out", + create_python_env=False, # Don't create actual Python env + no_hatch_mcp_server=True, + ) # Manually set python_env info to simulate having Python support self.env_manager._environments["test_mcp_opt_out"]["python_env"] = { @@ -618,25 +790,31 @@ def mock_install(env_name, tag=None): "python_executable": "/fake/python", "created_at": datetime.now().isoformat(), "version": "3.11.0", - "manager": "conda" + "manager": "conda", } - + self.assertTrue(success, "Environment creation should succeed") - self.assertFalse(install_called, "MCP server installation should not be called when opted out") - + self.assertFalse( + install_called, + "MCP server installation should not be called when opted out", + ) + # Verify MCP server package is NOT in environment env_data = self.env_manager._environments["test_mcp_opt_out"] packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] expected_name = "hatch_mcp_server @ git+https://github.com/CrackingShells/Hatch-MCP-Server.git" - self.assertNotIn(expected_name, package_names, "MCP server should not be installed when opted out") + self.assertNotIn( + expected_name, + package_names, + "MCP server should not be installed when opted out", + ) finally: # Restore original method self.env_manager._install_hatch_mcp_server = original_install @regression_test - @slow_test def test_create_environment_with_mcp_server_custom_tag(self): """Test creating environment with custom MCP server tag.""" # Mock the MCP server installation to avoid actual network calls @@ -647,25 +825,31 @@ def mock_install(env_name, tag=None): nonlocal installed_tag installed_tag = tag # Simulate successful installation - package_git_url = f"git+https://github.com/CrackingShells/Hatch-MCP-Server.git@{tag}" + package_git_url = ( + f"git+https://github.com/CrackingShells/Hatch-MCP-Server.git@{tag}" + ) env_data = self.env_manager._environments[env_name] - env_data["packages"].append({ - "name": f"hatch_mcp_server @ {package_git_url}", - "version": tag or "latest", - "type": "python", - "source": package_git_url, - "installed_at": datetime.now().isoformat() - }) + env_data["packages"].append( + { + "name": f"hatch_mcp_server @ {package_git_url}", + "version": tag or "latest", + "type": "python", + "source": package_git_url, + "installed_at": datetime.now().isoformat(), + } + ) self.env_manager._install_hatch_mcp_server = mock_install try: # Create environment without Python environment - success = self.env_manager.create_environment("test_mcp_custom_tag", - description="Test MCP custom tag", - create_python_env=False, # Don't create actual Python env - no_hatch_mcp_server=False, - hatch_mcp_server_tag="v0.1.0") + success = self.env_manager.create_environment( + "test_mcp_custom_tag", + description="Test MCP custom tag", + create_python_env=False, # Don't create actual Python env + no_hatch_mcp_server=False, + hatch_mcp_server_tag="v0.1.0", + ) # Manually set python_env info to simulate having Python support self.env_manager._environments["test_mcp_custom_tag"]["python_env"] = { @@ -674,29 +858,38 @@ def mock_install(env_name, tag=None): "python_executable": "/fake/python", "created_at": datetime.now().isoformat(), "version": "3.11.0", - "manager": "conda" + "manager": "conda", } - + # Now call the MCP installation manually (since we bypassed Python env creation) self.env_manager._install_hatch_mcp_server("test_mcp_custom_tag", "v0.1.0") - + self.assertTrue(success, "Environment creation should succeed") - self.assertEqual(installed_tag, "v0.1.0", "Custom tag should be passed to installation") - + self.assertEqual( + installed_tag, "v0.1.0", "Custom tag should be passed to installation" + ) + # Verify MCP server package is in environment with correct version env_data = self.env_manager._environments["test_mcp_custom_tag"] packages = env_data.get("packages", []) expected_name = "hatch_mcp_server @ git+https://github.com/CrackingShells/Hatch-MCP-Server.git@v0.1.0" mcp_packages = [pkg for pkg in packages if pkg["name"] == expected_name] - self.assertEqual(len(mcp_packages), 1, "Exactly one MCP server package should be installed with correct name syntax") - self.assertEqual(mcp_packages[0]["version"], "v0.1.0", "MCP server should have correct version") - + self.assertEqual( + len(mcp_packages), + 1, + "Exactly one MCP server package should be installed with correct name syntax", + ) + self.assertEqual( + mcp_packages[0]["version"], + "v0.1.0", + "MCP server should have correct version", + ) + finally: # Restore original method self.env_manager._install_hatch_mcp_server = original_install @regression_test - @slow_test def test_create_environment_no_python_no_mcp_server(self): """Test creating environment without Python support should not install MCP server.""" # Mock the MCP server installation to track calls @@ -711,27 +904,33 @@ def mock_install(env_name, tag=None): try: # Create environment without Python support - success = self.env_manager.create_environment("test_no_python", - description="Test no Python", - create_python_env=False, - no_hatch_mcp_server=False) + success = self.env_manager.create_environment( + "test_no_python", + description="Test no Python", + create_python_env=False, + no_hatch_mcp_server=False, + ) self.assertTrue(success, "Environment creation should succeed") - self.assertFalse(install_called, "MCP server installation should not be called without Python environment") + self.assertFalse( + install_called, + "MCP server installation should not be called without Python environment", + ) finally: # Restore original method self.env_manager._install_hatch_mcp_server = original_install @regression_test - @slow_test def test_install_mcp_server_existing_environment(self): """Test installing MCP server in an existing environment.""" # Create environment first without Python environment - success = self.env_manager.create_environment("test_existing_mcp", - description="Test existing MCP", - create_python_env=False, # Don't create actual Python env - no_hatch_mcp_server=True) # Opt out initially + success = self.env_manager.create_environment( + "test_existing_mcp", + description="Test existing MCP", + create_python_env=False, # Don't create actual Python env + no_hatch_mcp_server=True, + ) # Opt out initially self.assertTrue(success, "Environment creation should succeed") # Manually set python_env info to simulate having Python support @@ -741,14 +940,14 @@ def test_install_mcp_server_existing_environment(self): "python_executable": "/fake/python", "created_at": datetime.now().isoformat(), "version": "3.11.0", - "manager": "conda" + "manager": "conda", } - + # Mock the MCP server installation original_install = self.env_manager._install_hatch_mcp_server installed_env = None installed_tag = None - + def mock_install(env_name, tag=None): nonlocal installed_env, installed_tag installed_env = env_name @@ -756,41 +955,54 @@ def mock_install(env_name, tag=None): # Simulate successful installation package_git_url = f"git+https://github.com/CrackingShells/Hatch-MCP-Server.git@{tag if tag else 'main'}" env_data = self.env_manager._environments[env_name] - env_data["packages"].append({ - "name": f"hatch_mcp_server @ {package_git_url}", - "version": tag or "latest", - "type": "python", - "source": package_git_url, - "installed_at": datetime.now().isoformat() - }) - + env_data["packages"].append( + { + "name": f"hatch_mcp_server @ {package_git_url}", + "version": tag or "latest", + "type": "python", + "source": package_git_url, + "installed_at": datetime.now().isoformat(), + } + ) + self.env_manager._install_hatch_mcp_server = mock_install - + try: # Install MCP server with custom tag success = self.env_manager.install_mcp_server("test_existing_mcp", "v0.2.0") - + self.assertTrue(success, "MCP server installation should succeed") - self.assertEqual(installed_env, "test_existing_mcp", "MCP server should be installed in correct environment") - self.assertEqual(installed_tag, "v0.2.0", "Custom tag should be passed to installation") - + self.assertEqual( + installed_env, + "test_existing_mcp", + "MCP server should be installed in correct environment", + ) + self.assertEqual( + installed_tag, "v0.2.0", "Custom tag should be passed to installation" + ) + # Verify MCP server package is in environment env_data = self.env_manager._environments["test_existing_mcp"] packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] - expected_name = f"hatch_mcp_server @ git+https://github.com/CrackingShells/Hatch-MCP-Server.git@v0.2.0" - self.assertIn(expected_name, package_names, "MCP server should be installed in environment with correct name syntax") + expected_name = "hatch_mcp_server @ git+https://github.com/CrackingShells/Hatch-MCP-Server.git@v0.2.0" + self.assertIn( + expected_name, + package_names, + "MCP server should be installed in environment with correct name syntax", + ) finally: # Restore original method self.env_manager._install_hatch_mcp_server = original_install @regression_test - @slow_test def test_create_python_environment_only_with_mcp_wrapper(self): """Test creating Python environment only with MCP wrapper support.""" # First create a Hatch environment without Python - self.env_manager.create_environment("test_python_only", "Test Python Only", create_python_env=False) + self.env_manager.create_environment( + "test_python_only", "Test Python Only", create_python_env=False + ) self.assertTrue(self.env_manager.environment_exists("test_python_only")) # Mock Python environment creation to simulate success @@ -799,111 +1011,148 @@ def test_create_python_environment_only_with_mcp_wrapper(self): def mock_create_python_env(env_name, python_version=None, force=False): return True - + def mock_get_env_info(env_name): return { "conda_env_name": f"hatch-{env_name}", "python_executable": f"/path/to/conda/envs/hatch-{env_name}/bin/python", "python_version": "3.11.0", - "manager": "conda" + "manager": "conda", } - + # Mock MCP wrapper installation installed_env = None installed_tag = None original_install = self.env_manager._install_hatch_mcp_server - + def mock_install(env_name, tag=None): nonlocal installed_env, installed_tag installed_env = env_name installed_tag = tag # Simulate adding MCP wrapper to environment - package_git_url = f"git+https://github.com/CrackingShells/Hatch-MCP-Server.git" + package_git_url = ( + "git+https://github.com/CrackingShells/Hatch-MCP-Server.git" + ) if tag: package_git_url += f"@{tag}" env_data = self.env_manager._environments[env_name] - env_data["packages"].append({ - "name": f"hatch_mcp_server @ {package_git_url}", - "version": tag or "latest", - "type": "python", - "source": package_git_url, - "installed_at": datetime.now().isoformat() - }) - - self.env_manager.python_env_manager.create_python_environment = mock_create_python_env + env_data["packages"].append( + { + "name": f"hatch_mcp_server @ {package_git_url}", + "version": tag or "latest", + "type": "python", + "source": package_git_url, + "installed_at": datetime.now().isoformat(), + } + ) + + self.env_manager.python_env_manager.create_python_environment = ( + mock_create_python_env + ) self.env_manager.python_env_manager.get_environment_info = mock_get_env_info self.env_manager._install_hatch_mcp_server = mock_install - + try: # Test creating Python environment with default MCP wrapper installation - success = self.env_manager.create_python_environment_only("test_python_only") - + success = self.env_manager.create_python_environment_only( + "test_python_only" + ) + self.assertTrue(success, "Python environment creation should succeed") - self.assertEqual(installed_env, "test_python_only", "MCP wrapper should be installed in correct environment") + self.assertEqual( + installed_env, + "test_python_only", + "MCP wrapper should be installed in correct environment", + ) self.assertIsNone(installed_tag, "Default tag should be None") - + # Verify environment metadata was updated env_data = self.env_manager._environments["test_python_only"] - self.assertTrue(env_data.get("python_environment"), "Python environment flag should be set") - self.assertIsNotNone(env_data.get("python_env"), "Python environment info should be set") - + self.assertTrue( + env_data.get("python_environment"), + "Python environment flag should be set", + ) + self.assertIsNotNone( + env_data.get("python_env"), "Python environment info should be set" + ) + # Verify MCP wrapper was installed packages = env_data.get("packages", []) package_names = [pkg["name"] for pkg in packages] expected_name = "hatch_mcp_server @ git+https://github.com/CrackingShells/Hatch-MCP-Server.git" - self.assertIn(expected_name, package_names, "MCP wrapper should be installed") - + self.assertIn( + expected_name, package_names, "MCP wrapper should be installed" + ) + # Reset for next test installed_env = None installed_tag = None env_data["packages"] = [] - + # Test creating Python environment with custom tag success = self.env_manager.create_python_environment_only( - "test_python_only", + "test_python_only", python_version="3.12", force=True, - hatch_mcp_server_tag="dev" + hatch_mcp_server_tag="dev", + ) + + self.assertTrue( + success, "Python environment creation with custom tag should succeed" ) - - self.assertTrue(success, "Python environment creation with custom tag should succeed") - self.assertEqual(installed_tag, "dev", "Custom tag should be passed to MCP wrapper installation") - - # Reset for next test + self.assertEqual( + installed_tag, + "dev", + "Custom tag should be passed to MCP wrapper installation", + ) + + # Reset for next test installed_env = None env_data["packages"] = [] - + # Test opting out of MCP wrapper installation success = self.env_manager.create_python_environment_only( - "test_python_only", - force=True, - no_hatch_mcp_server=True + "test_python_only", force=True, no_hatch_mcp_server=True + ) + + self.assertTrue( + success, + "Python environment creation without MCP wrapper should succeed", + ) + self.assertIsNone( + installed_env, "MCP wrapper should not be installed when opted out" ) - - self.assertTrue(success, "Python environment creation without MCP wrapper should succeed") - self.assertIsNone(installed_env, "MCP wrapper should not be installed when opted out") - + # Verify no MCP wrapper was installed packages = env_data.get("packages", []) - self.assertEqual(len(packages), 0, "No packages should be installed when MCP wrapper is opted out") - + self.assertEqual( + len(packages), + 0, + "No packages should be installed when MCP wrapper is opted out", + ) + finally: # Restore original methods - self.env_manager.python_env_manager.create_python_environment = original_create + self.env_manager.python_env_manager.create_python_environment = ( + original_create + ) self.env_manager.python_env_manager.get_environment_info = original_get_info self.env_manager._install_hatch_mcp_server = original_install # Non-TTY Handling Backward Compatibility Tests @regression_test - @patch('sys.stdin.isatty', return_value=False) + @patch("sys.stdin.isatty", return_value=False) def test_add_package_non_tty_auto_approve(self, mock_isatty): """Test package addition in non-TTY environment (backward compatibility).""" # Create environment - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) # Test existing auto_approve=True behavior is preserved from test_data_utils import TestDataLoader + test_loader = TestDataLoader() base_pkg_path = test_loader.packages_dir / "basic" / "base_pkg" @@ -913,20 +1162,26 @@ def test_add_package_non_tty_auto_approve(self, mock_isatty): result = self.env_manager.add_package_to_environment( str(base_pkg_path), "test_env", - auto_approve=False # Should auto-approve due to non-TTY detection + auto_approve=False, # Should auto-approve due to non-TTY detection ) - self.assertTrue(result, "Non-TTY environment should auto-approve even with auto_approve=False") + self.assertTrue( + result, + "Non-TTY environment should auto-approve even with auto_approve=False", + ) mock_isatty.assert_called() # Verify TTY detection was called @regression_test - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': '1'}) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "1"}) def test_add_package_environment_variable_compatibility(self): """Test new environment variable doesn't break existing workflows.""" # Verify existing auto_approve=False behavior with environment variable - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) from test_data_utils import TestDataLoader + test_loader = TestDataLoader() base_pkg_path = test_loader.packages_dir / "basic" / "base_pkg" @@ -936,19 +1191,22 @@ def test_add_package_environment_variable_compatibility(self): result = self.env_manager.add_package_to_environment( str(base_pkg_path), "test_env", - auto_approve=False # Should be overridden by environment variable + auto_approve=False, # Should be overridden by environment variable ) self.assertTrue(result, "Environment variable should enable auto-approval") @regression_test - @patch('sys.stdin.isatty', return_value=False) + @patch("sys.stdin.isatty", return_value=False) def test_add_package_with_dependencies_non_tty(self, mock_isatty): """Test package with dependencies in non-TTY environment.""" # Create environment - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) from test_data_utils import TestDataLoader + test_loader = TestDataLoader() # Test with a package that has dependencies @@ -960,19 +1218,22 @@ def test_add_package_with_dependencies_non_tty(self, mock_isatty): result = self.env_manager.add_package_to_environment( str(simple_pkg_path), "test_env", - auto_approve=False # Should auto-approve due to non-TTY + auto_approve=False, # Should auto-approve due to non-TTY ) self.assertTrue(result, "Package with dependencies should install in non-TTY") mock_isatty.assert_called() @regression_test - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': 'yes'}) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "yes"}) def test_environment_variable_case_variations(self): """Test environment variable with different case variations.""" - self.env_manager.create_environment("test_env", "Test environment", create_python_env=False) + self.env_manager.create_environment( + "test_env", "Test environment", create_python_env=False + ) from test_data_utils import TestDataLoader + test_loader = TestDataLoader() base_pkg_path = test_loader.packages_dir / "basic" / "base_pkg" @@ -980,12 +1241,13 @@ def test_environment_variable_case_variations(self): self.skipTest(f"Test package not found: {base_pkg_path}") result = self.env_manager.add_package_to_environment( - str(base_pkg_path), - "test_env", - auto_approve=False + str(base_pkg_path), "test_env", auto_approve=False + ) + + self.assertTrue( + result, "Environment variable 'yes' should enable auto-approval" ) - self.assertTrue(result, "Environment variable 'yes' should enable auto-approval") if __name__ == "__main__": unittest.main() diff --git a/tests/test_hatch_installer.py b/tests/test_hatch_installer.py index d8caadf..2c8c9b7 100644 --- a/tests/test_hatch_installer.py +++ b/tests/test_hatch_installer.py @@ -1,19 +1,18 @@ import unittest import tempfile import shutil -import logging from pathlib import Path from datetime import datetime -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test from hatch.installers.hatch_installer import HatchInstaller from hatch.package_loader import HatchPackageLoader from hatch_validator.package_validator import HatchPackageValidator -from hatch_validator.package.package_service import PackageService from hatch.installers.installation_context import InstallationStatus + class TestHatchInstaller(unittest.TestCase): """Tests for the HatchInstaller using dummy packages from Hatching-Dev.""" @@ -21,7 +20,13 @@ class TestHatchInstaller(unittest.TestCase): def setUpClass(cls): # Path to Hatching-Dev dummy packages cls.hatch_dev_path = Path(__file__).parent.parent.parent / "Hatching-Dev" - assert cls.hatch_dev_path.exists(), f"Hatching-Dev directory not found at {cls.hatch_dev_path}" + + # Skip all tests if Hatching-Dev directory doesn't exist + if not cls.hatch_dev_path.exists(): + raise unittest.SkipTest( + f"Hatching-Dev directory not found at {cls.hatch_dev_path}. " + "These tests require the Hatching-Dev sibling repository." + ) # Build a mock registry from Hatching-Dev packages (pattern from test_package_validator.py) cls.registry_data = cls._build_test_registry(cls.hatch_dev_path) @@ -39,18 +44,25 @@ def _build_test_registry(hatch_dev_path): "name": "Hatch-Dev", "url": "file://" + str(hatch_dev_path), "packages": [], - "last_indexed": datetime.now().isoformat() + "last_indexed": datetime.now().isoformat(), } - ] + ], } # Use self-contained test packages instead of external Hatching-Dev from test_data_utils import TestDataLoader + test_loader = TestDataLoader() pkg_names = [ - "base_pkg", "utility_pkg", "python_dep_pkg", - "circular_dep_pkg", "circular_dep_pkg_b", "complex_dep_pkg", - "simple_dep_pkg", "invalid_dep_pkg", "version_conflict_pkg" + "base_pkg", + "utility_pkg", + "python_dep_pkg", + "circular_dep_pkg", + "circular_dep_pkg_b", + "complex_dep_pkg", + "simple_dep_pkg", + "invalid_dep_pkg", + "version_conflict_pkg", ] for pkg_name in pkg_names: # Map to self-contained package locations @@ -58,15 +70,21 @@ def _build_test_registry(hatch_dev_path): pkg_path = test_loader.packages_dir / "basic" / pkg_name elif pkg_name in ["complex_dep_pkg", "simple_dep_pkg", "python_dep_pkg"]: pkg_path = test_loader.packages_dir / "dependencies" / pkg_name - elif pkg_name in ["circular_dep_pkg", "circular_dep_pkg_b", "invalid_dep_pkg", "version_conflict_pkg"]: + elif pkg_name in [ + "circular_dep_pkg", + "circular_dep_pkg_b", + "invalid_dep_pkg", + "version_conflict_pkg", + ]: pkg_path = test_loader.packages_dir / "error_scenarios" / pkg_name else: pkg_path = test_loader.packages_dir / pkg_name if pkg_path.exists(): metadata_path = pkg_path / "hatch_metadata.json" if metadata_path.exists(): - with open(metadata_path, 'r') as f: + with open(metadata_path, "r") as f: import json + metadata = json.load(f) pkg_entry = { "name": metadata.get("name", pkg_name), @@ -79,27 +97,41 @@ def _build_test_registry(hatch_dev_path): "version": metadata.get("version", "1.0.0"), "release_uri": f"file://{pkg_path}", "author": { - "GitHubID": metadata.get("author", {}).get("name", "test_user"), - "email": metadata.get("author", {}).get("email", "test@example.com") + "GitHubID": metadata.get("author", {}).get( + "name", "test_user" + ), + "email": metadata.get("author", {}).get( + "email", "test@example.com" + ), }, "added_date": datetime.now().isoformat(), "hatch_dependencies_added": [ { "name": dep["name"], - "version_constraint": dep.get("version_constraint", "") + "version_constraint": dep.get( + "version_constraint", "" + ), } - for dep in metadata.get("hatch_dependencies", []) + for dep in metadata.get( + "hatch_dependencies", [] + ) ], "python_dependencies_added": [ { "name": dep["name"], - "version_constraint": dep.get("version_constraint", ""), - "package_manager": dep.get("package_manager", "pip") + "version_constraint": dep.get( + "version_constraint", "" + ), + "package_manager": dep.get( + "package_manager", "pip" + ), } - for dep in metadata.get("python_dependencies", []) + for dep in metadata.get( + "python_dependencies", [] + ) ], } - ] + ], } registry["repositories"][0]["packages"].append(pkg_entry) return registry @@ -118,22 +150,26 @@ def test_installer_can_install_and_uninstall(self): """Test the full install and uninstall cycle for a dummy Hatch package using the installer.""" pkg_name = "base_pkg" from test_data_utils import TestDataLoader + test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / pkg_name metadata_path = pkg_path / "hatch_metadata.json" - with open(metadata_path, 'r') as f: + with open(metadata_path, "r") as f: import json + metadata = json.load(f) dependency = { "name": pkg_name, "version_constraint": metadata.get("version", "1.0.0"), "resolved_version": metadata.get("version", "1.0.0"), "type": "hatch", - "uri": f"file://{pkg_path}" + "uri": f"file://{pkg_path}", } + # Prepare a minimal InstallationContext class DummyContext: environment_path = str(self.target_dir) + context = DummyContext() # Install result = self.installer.install(dependency, context) @@ -159,10 +195,12 @@ def test_installation_error_on_missing_uri(self): "name": pkg_name, "version_constraint": "1.0.0", "resolved_version": "1.0.0", - "type": "hatch" + "type": "hatch", } + class DummyContext: environment_path = str(self.target_dir) + context = DummyContext() with self.assertRaises(Exception): self.installer.install(dependency, context) @@ -175,5 +213,6 @@ def test_can_install_method(self): dep2 = {"type": "python"} self.assertFalse(self.installer.can_install(dep2)) + if __name__ == "__main__": unittest.main() diff --git a/tests/test_installer_base.py b/tests/test_installer_base.py index 0dfc212..09f2aea 100644 --- a/tests/test_installer_base.py +++ b/tests/test_installer_base.py @@ -1,106 +1,130 @@ -import sys import unittest import logging import tempfile import shutil from pathlib import Path -from unittest.mock import Mock from typing import Dict, Any, List -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test # Import path management removed - using test_data_utils for test dependencies -from hatch.installers.installer_base import ( - DependencyInstaller, - InstallationError -) +from hatch.installers.installer_base import DependencyInstaller, InstallationError from hatch.installers.installation_context import ( - InstallationContext, + InstallationContext, InstallationResult, - InstallationStatus + InstallationStatus, ) # Configure logging logging.basicConfig( - level=logging.INFO, - format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' + level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s" ) logger = logging.getLogger("hatch.installer_interface_tests") + class MockInstaller(DependencyInstaller): """Mock installer for testing the base interface.""" - + @property def installer_type(self) -> str: return "mock" - + @property def supported_schemes(self) -> List[str]: return ["test", "mock"] - + def can_install(self, dependency: Dict[str, Any]) -> bool: return dependency.get("type") == "mock" - - def install(self, dependency: Dict[str, Any], context: InstallationContext, - progress_callback=None) -> InstallationResult: + + def install( + self, + dependency: Dict[str, Any], + context: InstallationContext, + progress_callback=None, + ) -> InstallationResult: return InstallationResult( dependency_name=dependency["name"], status=InstallationStatus.COMPLETED, installed_path=context.environment_path / dependency["name"], - installed_version=dependency["resolved_version"] + installed_version=dependency["resolved_version"], ) + class BaseInstallerTests(unittest.TestCase): """Tests for the DependencyInstaller base class interface.""" - + def setUp(self): """Set up test environment before each test.""" # Create a temporary directory for test environments self.temp_dir = tempfile.mkdtemp() self.env_path = Path(self.temp_dir) / "test_env" self.env_path.mkdir(parents=True, exist_ok=True) - + # Create a mock installer instance for testing self.installer = MockInstaller() - + # Create test context self.context = InstallationContext( - environment_path=self.env_path, - environment_name="test_env" + environment_path=self.env_path, environment_name="test_env" ) - + logger.info(f"Set up test environment at {self.temp_dir}") - + def tearDown(self): """Clean up test environment after each test.""" - if hasattr(self, 'temp_dir') and Path(self.temp_dir).exists(): + if hasattr(self, "temp_dir") and Path(self.temp_dir).exists(): shutil.rmtree(self.temp_dir, ignore_errors=True) logger.info(f"Cleaned up test environment at {self.temp_dir}") + @regression_test def test_installation_context_creation(self): """Test that InstallationContext can be created with required fields.""" context = InstallationContext( - environment_path=Path("/test/env"), - environment_name="test_env" + environment_path=Path("/test/env"), environment_name="test_env" + ) + self.assertEqual( + context.environment_path, + Path("/test/env"), + f"Expected environment_path=/test/env, got {context.environment_path}", + ) + self.assertEqual( + context.environment_name, + "test_env", + f"Expected environment_name='test_env', got {context.environment_name}", + ) + self.assertTrue( + context.parallel_enabled, + f"Expected parallel_enabled=True, got {context.parallel_enabled}", + ) # Default value + self.assertEqual( + context.get_config("nonexistent", "default"), + "default", + f"Expected default config fallback, got {context.get_config('nonexistent', 'default')}", ) - self.assertEqual(context.environment_path, Path("/test/env"), f"Expected environment_path=/test/env, got {context.environment_path}") - self.assertEqual(context.environment_name, "test_env", f"Expected environment_name='test_env', got {context.environment_name}") - self.assertTrue(context.parallel_enabled, f"Expected parallel_enabled=True, got {context.parallel_enabled}") # Default value - self.assertEqual(context.get_config("nonexistent", "default"), "default", f"Expected default config fallback, got {context.get_config('nonexistent', 'default')}") logger.info("InstallationContext creation test passed") + @regression_test def test_installation_context_with_config(self): """Test InstallationContext with extra configuration.""" context = InstallationContext( environment_path=Path("/test/env"), environment_name="test_env", - extra_config={"custom_setting": "value"} + extra_config={"custom_setting": "value"}, + ) + self.assertEqual( + context.get_config("custom_setting"), + "value", + f"Expected custom_setting='value', got {context.get_config('custom_setting')}", + ) + self.assertEqual( + context.get_config("missing_key", "fallback"), + "fallback", + f"Expected fallback for missing_key, got {context.get_config('missing_key', 'fallback')}", ) - self.assertEqual(context.get_config("custom_setting"), "value", f"Expected custom_setting='value', got {context.get_config('custom_setting')}") - self.assertEqual(context.get_config("missing_key", "fallback"), "fallback", f"Expected fallback for missing_key, got {context.get_config('missing_key', 'fallback')}") logger.info("InstallationContext with config test passed") + @regression_test def test_installation_result_creation(self): """Test that InstallationResult can be created.""" @@ -108,37 +132,82 @@ def test_installation_result_creation(self): dependency_name="test_package", status=InstallationStatus.COMPLETED, installed_path=Path("/env/test_package"), - installed_version="1.0.0" + installed_version="1.0.0", + ) + self.assertEqual( + result.dependency_name, + "test_package", + f"Expected dependency_name='test_package', got {result.dependency_name}", + ) + self.assertEqual( + result.status, + InstallationStatus.COMPLETED, + f"Expected status=COMPLETED, got {result.status}", + ) + self.assertEqual( + result.installed_path, + Path("/env/test_package"), + f"Expected installed_path=/env/test_package, got {result.installed_path}", + ) + self.assertEqual( + result.installed_version, + "1.0.0", + f"Expected installed_version='1.0.0', got {result.installed_version}", ) - self.assertEqual(result.dependency_name, "test_package", f"Expected dependency_name='test_package', got {result.dependency_name}") - self.assertEqual(result.status, InstallationStatus.COMPLETED, f"Expected status=COMPLETED, got {result.status}") - self.assertEqual(result.installed_path, Path("/env/test_package"), f"Expected installed_path=/env/test_package, got {result.installed_path}") - self.assertEqual(result.installed_version, "1.0.0", f"Expected installed_version='1.0.0', got {result.installed_version}") logger.info("InstallationResult creation test passed") + @regression_test def test_installation_error(self): """Test InstallationError creation and attributes.""" error = InstallationError( message="Installation failed", dependency_name="test_package", - error_code="DOWNLOAD_FAILED" + error_code="DOWNLOAD_FAILED", + ) + self.assertEqual( + error.message, + "Installation failed", + f"Expected error message 'Installation failed', got '{error.message}'", + ) + self.assertEqual( + error.dependency_name, + "test_package", + f"Expected dependency_name='test_package', got {error.dependency_name}", + ) + self.assertEqual( + error.error_code, + "DOWNLOAD_FAILED", + f"Expected error_code='DOWNLOAD_FAILED', got {error.error_code}", ) - self.assertEqual(error.message, "Installation failed", f"Expected error message 'Installation failed', got '{error.message}'") - self.assertEqual(error.dependency_name, "test_package", f"Expected dependency_name='test_package', got {error.dependency_name}") - self.assertEqual(error.error_code, "DOWNLOAD_FAILED", f"Expected error_code='DOWNLOAD_FAILED', got {error.error_code}") logger.info("InstallationError test passed") + @regression_test def test_mock_installer_interface(self): """Test that MockInstaller implements the interface correctly.""" # Test properties - self.assertEqual(self.installer.installer_type, "mock", f"Expected installer_type='mock', got {self.installer.installer_type}") - self.assertEqual(self.installer.supported_schemes, ["test", "mock"], f"Expected supported_schemes=['test', 'mock'], got {self.installer.supported_schemes}") + self.assertEqual( + self.installer.installer_type, + "mock", + f"Expected installer_type='mock', got {self.installer.installer_type}", + ) + self.assertEqual( + self.installer.supported_schemes, + ["test", "mock"], + f"Expected supported_schemes=['test', 'mock'], got {self.installer.supported_schemes}", + ) # Test can_install mock_dep = {"type": "mock", "name": "test"} non_mock_dep = {"type": "other", "name": "test"} - self.assertTrue(self.installer.can_install(mock_dep), f"Expected can_install to be True for {mock_dep}") - self.assertFalse(self.installer.can_install(non_mock_dep), f"Expected can_install to be False for {non_mock_dep}") + self.assertTrue( + self.installer.can_install(mock_dep), + f"Expected can_install to be True for {mock_dep}", + ) + self.assertFalse( + self.installer.can_install(non_mock_dep), + f"Expected can_install to be False for {non_mock_dep}", + ) logger.info("MockInstaller interface test passed") + @regression_test def test_mock_installer_install(self): """Test the install method of MockInstaller.""" @@ -146,76 +215,151 @@ def test_mock_installer_install(self): "name": "test_package", "type": "mock", "version_constraint": ">=1.0.0", - "resolved_version": "1.2.0" + "resolved_version": "1.2.0", } result = self.installer.install(dependency, self.context) - self.assertEqual(result.dependency_name, "test_package", f"Expected dependency_name='test_package', got {result.dependency_name}") - self.assertEqual(result.status, InstallationStatus.COMPLETED, f"Expected status=COMPLETED, got {result.status}") - self.assertEqual(result.installed_path, self.env_path / "test_package", f"Expected installed_path={self.env_path / 'test_package'}, got {result.installed_path}") - self.assertEqual(result.installed_version, "1.2.0", f"Expected installed_version='1.2.0', got {result.installed_version}") + self.assertEqual( + result.dependency_name, + "test_package", + f"Expected dependency_name='test_package', got {result.dependency_name}", + ) + self.assertEqual( + result.status, + InstallationStatus.COMPLETED, + f"Expected status=COMPLETED, got {result.status}", + ) + self.assertEqual( + result.installed_path, + self.env_path / "test_package", + f"Expected installed_path={self.env_path / 'test_package'}, got {result.installed_path}", + ) + self.assertEqual( + result.installed_version, + "1.2.0", + f"Expected installed_version='1.2.0', got {result.installed_version}", + ) logger.info("MockInstaller install test passed") + @regression_test def test_mock_installer_validation(self): """Test dependency validation.""" valid_dep = { "name": "test", "version_constraint": ">=1.0.0", - "resolved_version": "1.0.0" + "resolved_version": "1.0.0", } invalid_dep = { "name": "test" # Missing required fields } - self.assertTrue(self.installer.validate_dependency(valid_dep), f"Expected valid dependency to pass validation: {valid_dep}") - self.assertFalse(self.installer.validate_dependency(invalid_dep), f"Expected invalid dependency to fail validation: {invalid_dep}") + self.assertTrue( + self.installer.validate_dependency(valid_dep), + f"Expected valid dependency to pass validation: {valid_dep}", + ) + self.assertFalse( + self.installer.validate_dependency(invalid_dep), + f"Expected invalid dependency to fail validation: {invalid_dep}", + ) logger.info("MockInstaller validation test passed") + @regression_test def test_mock_installer_get_installation_info(self): """Test getting installation information.""" dependency = { "name": "test_package", "type": "mock", - "resolved_version": "1.0.0" + "resolved_version": "1.0.0", } info = self.installer.get_installation_info(dependency, self.context) - self.assertEqual(info["installer_type"], "mock", f"Expected installer_type='mock', got {info['installer_type']}") - self.assertEqual(info["dependency_name"], "test_package", f"Expected dependency_name='test_package', got {info['dependency_name']}") - self.assertEqual(info["resolved_version"], "1.0.0", f"Expected resolved_version='1.0.0', got {info['resolved_version']}") - self.assertEqual(info["target_path"], str(self.env_path), f"Expected target_path={self.env_path}, got {info['target_path']}") - self.assertTrue(info["supported"], f"Expected supported=True, got {info['supported']}") + self.assertEqual( + info["installer_type"], + "mock", + f"Expected installer_type='mock', got {info['installer_type']}", + ) + self.assertEqual( + info["dependency_name"], + "test_package", + f"Expected dependency_name='test_package', got {info['dependency_name']}", + ) + self.assertEqual( + info["resolved_version"], + "1.0.0", + f"Expected resolved_version='1.0.0', got {info['resolved_version']}", + ) + self.assertEqual( + info["target_path"], + str(self.env_path), + f"Expected target_path={self.env_path}, got {info['target_path']}", + ) + self.assertTrue( + info["supported"], f"Expected supported=True, got {info['supported']}" + ) logger.info("MockInstaller get_installation_info test passed") + @regression_test def test_mock_installer_uninstall_not_implemented(self): """Test that uninstall raises NotImplementedError by default.""" dependency = {"name": "test", "type": "mock"} - with self.assertRaises(NotImplementedError, msg="Expected NotImplementedError for uninstall on MockInstaller"): + with self.assertRaises( + NotImplementedError, + msg="Expected NotImplementedError for uninstall on MockInstaller", + ): self.installer.uninstall(dependency, self.context) logger.info("MockInstaller uninstall NotImplementedError test passed") + @regression_test def test_installation_status_enum(self): """Test InstallationStatus enum values.""" - self.assertEqual(InstallationStatus.PENDING.value, "pending", f"Expected PENDING='pending', got {InstallationStatus.PENDING.value}") - self.assertEqual(InstallationStatus.IN_PROGRESS.value, "in_progress", f"Expected IN_PROGRESS='in_progress', got {InstallationStatus.IN_PROGRESS.value}") - self.assertEqual(InstallationStatus.COMPLETED.value, "completed", f"Expected COMPLETED='completed', got {InstallationStatus.COMPLETED.value}") - self.assertEqual(InstallationStatus.FAILED.value, "failed", f"Expected FAILED='failed', got {InstallationStatus.FAILED.value}") - self.assertEqual(InstallationStatus.ROLLED_BACK.value, "rolled_back", f"Expected ROLLED_BACK='rolled_back', got {InstallationStatus.ROLLED_BACK.value}") + self.assertEqual( + InstallationStatus.PENDING.value, + "pending", + f"Expected PENDING='pending', got {InstallationStatus.PENDING.value}", + ) + self.assertEqual( + InstallationStatus.IN_PROGRESS.value, + "in_progress", + f"Expected IN_PROGRESS='in_progress', got {InstallationStatus.IN_PROGRESS.value}", + ) + self.assertEqual( + InstallationStatus.COMPLETED.value, + "completed", + f"Expected COMPLETED='completed', got {InstallationStatus.COMPLETED.value}", + ) + self.assertEqual( + InstallationStatus.FAILED.value, + "failed", + f"Expected FAILED='failed', got {InstallationStatus.FAILED.value}", + ) + self.assertEqual( + InstallationStatus.ROLLED_BACK.value, + "rolled_back", + f"Expected ROLLED_BACK='rolled_back', got {InstallationStatus.ROLLED_BACK.value}", + ) logger.info("InstallationStatus enum test passed") + @regression_test def test_progress_callback_support(self): """Test that installer accepts progress callback.""" dependency = { "name": "test_package", "type": "mock", - "resolved_version": "1.0.0" + "resolved_version": "1.0.0", } callback_called = [] + def progress_callback(progress: float, message: str = ""): callback_called.append((progress, message)) + # Install with callback - should not raise error result = self.installer.install(dependency, self.context, progress_callback) - self.assertEqual(result.status, InstallationStatus.COMPLETED, f"Expected status=COMPLETED, got {result.status}") + self.assertEqual( + result.status, + InstallationStatus.COMPLETED, + f"Expected status=COMPLETED, got {result.status}", + ) logger.info("Progress callback support test passed") + if __name__ == "__main__": # Run the tests unittest.main(verbosity=2) diff --git a/tests/test_mcp_atomic_operations.py b/tests/test_mcp_atomic_operations.py deleted file mode 100644 index 9703169..0000000 --- a/tests/test_mcp_atomic_operations.py +++ /dev/null @@ -1,276 +0,0 @@ -"""Tests for MCP atomic file operations. - -This module contains tests for atomic file operations and backup-aware -operations with host-agnostic design. -""" - -import unittest -import tempfile -import shutil -import json -from pathlib import Path -from unittest.mock import patch, mock_open - -from wobble.decorators import regression_test -from test_data_utils import MCPBackupTestDataLoader - -from hatch.mcp_host_config.backup import ( - AtomicFileOperations, - MCPHostConfigBackupManager, - BackupAwareOperation, - BackupError -) - - -class TestAtomicFileOperations(unittest.TestCase): - """Test atomic file operations with host-agnostic design.""" - - def setUp(self): - """Set up test environment.""" - self.temp_dir = Path(tempfile.mkdtemp(prefix="test_atomic_")) - self.test_file = self.temp_dir / "test_config.json" - self.backup_manager = MCPHostConfigBackupManager(backup_root=self.temp_dir / "backups") - self.atomic_ops = AtomicFileOperations() - self.test_data = MCPBackupTestDataLoader() - - def tearDown(self): - """Clean up test environment.""" - shutil.rmtree(self.temp_dir, ignore_errors=True) - - @regression_test - def test_atomic_write_success_host_agnostic(self): - """Test successful atomic write with any JSON configuration format.""" - test_data = self.test_data.load_host_agnostic_config("complex_server") - - result = self.atomic_ops.atomic_write_with_backup( - self.test_file, test_data, self.backup_manager, "claude-desktop" - ) - - self.assertTrue(result) - self.assertTrue(self.test_file.exists()) - - # Verify content (host-agnostic) - with open(self.test_file) as f: - written_data = json.load(f) - self.assertEqual(written_data, test_data) - - @regression_test - def test_atomic_write_with_existing_file(self): - """Test atomic write with existing file creates backup.""" - # Create initial file - initial_data = self.test_data.load_host_agnostic_config("simple_server") - with open(self.test_file, 'w') as f: - json.dump(initial_data, f) - - # Update with atomic write - new_data = self.test_data.load_host_agnostic_config("complex_server") - result = self.atomic_ops.atomic_write_with_backup( - self.test_file, new_data, self.backup_manager, "vscode" - ) - - self.assertTrue(result) - - # Verify backup was created - backups = self.backup_manager.list_backups("vscode") - self.assertEqual(len(backups), 1) - - # Verify backup contains original data - with open(backups[0].file_path) as f: - backup_data = json.load(f) - self.assertEqual(backup_data, initial_data) - - # Verify file contains new data - with open(self.test_file) as f: - current_data = json.load(f) - self.assertEqual(current_data, new_data) - - @regression_test - def test_atomic_write_skip_backup(self): - """Test atomic write with backup skipped.""" - # Create initial file - initial_data = self.test_data.load_host_agnostic_config("simple_server") - with open(self.test_file, 'w') as f: - json.dump(initial_data, f) - - # Update with atomic write, skipping backup - new_data = self.test_data.load_host_agnostic_config("complex_server") - result = self.atomic_ops.atomic_write_with_backup( - self.test_file, new_data, self.backup_manager, "cursor", skip_backup=True - ) - - self.assertTrue(result) - - # Verify no backup was created - backups = self.backup_manager.list_backups("cursor") - self.assertEqual(len(backups), 0) - - # Verify file contains new data - with open(self.test_file) as f: - current_data = json.load(f) - self.assertEqual(current_data, new_data) - - @regression_test - def test_atomic_write_failure_rollback(self): - """Test atomic write failure triggers rollback.""" - # Create initial file - initial_data = self.test_data.load_host_agnostic_config("simple_server") - with open(self.test_file, 'w') as f: - json.dump(initial_data, f) - - # Mock file write failure after backup creation - with patch('builtins.open', side_effect=[ - # First call succeeds (backup creation) - open(self.test_file, 'r'), - # Second call fails (atomic write) - PermissionError("Access denied") - ]): - with self.assertRaises(BackupError): - self.atomic_ops.atomic_write_with_backup( - self.test_file, {"new": "data"}, self.backup_manager, "lmstudio" - ) - - # Verify original file is unchanged - with open(self.test_file) as f: - current_data = json.load(f) - self.assertEqual(current_data, initial_data) - - @regression_test - def test_atomic_copy_success(self): - """Test successful atomic copy operation.""" - source_file = self.temp_dir / "source.json" - target_file = self.temp_dir / "target.json" - - test_data = self.test_data.load_host_agnostic_config("simple_server") - with open(source_file, 'w') as f: - json.dump(test_data, f) - - result = self.atomic_ops.atomic_copy(source_file, target_file) - - self.assertTrue(result) - self.assertTrue(target_file.exists()) - - # Verify content integrity - with open(target_file) as f: - copied_data = json.load(f) - self.assertEqual(copied_data, test_data) - - @regression_test - def test_atomic_copy_failure_cleanup(self): - """Test atomic copy failure cleans up temporary files.""" - source_file = self.temp_dir / "source.json" - target_file = self.temp_dir / "target.json" - - test_data = self.test_data.load_host_agnostic_config("simple_server") - with open(source_file, 'w') as f: - json.dump(test_data, f) - - # Mock copy failure - with patch('shutil.copy2', side_effect=PermissionError("Access denied")): - result = self.atomic_ops.atomic_copy(source_file, target_file) - - self.assertFalse(result) - self.assertFalse(target_file.exists()) - - # Verify no temporary files left behind - temp_files = list(self.temp_dir.glob("*.tmp")) - self.assertEqual(len(temp_files), 0) - - -class TestBackupAwareOperation(unittest.TestCase): - """Test backup-aware operation API.""" - - def setUp(self): - """Set up test environment.""" - self.temp_dir = Path(tempfile.mkdtemp(prefix="test_backup_aware_")) - self.test_file = self.temp_dir / "test_config.json" - self.backup_manager = MCPHostConfigBackupManager(backup_root=self.temp_dir / "backups") - self.test_data = MCPBackupTestDataLoader() - - def tearDown(self): - """Clean up test environment.""" - shutil.rmtree(self.temp_dir, ignore_errors=True) - - @regression_test - def test_prepare_backup_success(self): - """Test explicit backup preparation.""" - # Create initial configuration - initial_data = self.test_data.load_host_agnostic_config("simple_server") - with open(self.test_file, 'w') as f: - json.dump(initial_data, f) - - # Test backup-aware operation - operation = BackupAwareOperation(self.backup_manager) - - # Test explicit backup preparation - backup_result = operation.prepare_backup(self.test_file, "gemini", no_backup=False) - self.assertIsNotNone(backup_result) - self.assertTrue(backup_result.success) - - # Verify backup was created - backups = self.backup_manager.list_backups("gemini") - self.assertEqual(len(backups), 1) - - @regression_test - def test_prepare_backup_no_backup_mode(self): - """Test no-backup mode.""" - # Create initial configuration - initial_data = self.test_data.load_host_agnostic_config("simple_server") - with open(self.test_file, 'w') as f: - json.dump(initial_data, f) - - operation = BackupAwareOperation(self.backup_manager) - - # Test no-backup mode - no_backup_result = operation.prepare_backup(self.test_file, "claude-code", no_backup=True) - self.assertIsNone(no_backup_result) - - # Verify no backup was created - backups = self.backup_manager.list_backups("claude-code") - self.assertEqual(len(backups), 0) - - @regression_test - def test_prepare_backup_failure_raises_exception(self): - """Test backup preparation failure raises BackupError.""" - # Test with nonexistent file - nonexistent_file = self.temp_dir / "nonexistent.json" - - operation = BackupAwareOperation(self.backup_manager) - - with self.assertRaises(BackupError): - operation.prepare_backup(nonexistent_file, "vscode", no_backup=False) - - @regression_test - def test_rollback_on_failure_success(self): - """Test successful rollback functionality.""" - # Create initial configuration - initial_data = self.test_data.load_host_agnostic_config("simple_server") - with open(self.test_file, 'w') as f: - json.dump(initial_data, f) - - operation = BackupAwareOperation(self.backup_manager) - - # Create backup - backup_result = operation.prepare_backup(self.test_file, "cursor", no_backup=False) - self.assertTrue(backup_result.success) - - # Modify file (simulate failed operation) - modified_data = self.test_data.load_host_agnostic_config("complex_server") - with open(self.test_file, 'w') as f: - json.dump(modified_data, f) - - # Test rollback functionality - rollback_success = operation.rollback_on_failure(backup_result, self.test_file, "cursor") - self.assertTrue(rollback_success) - - @regression_test - def test_rollback_on_failure_no_backup(self): - """Test rollback with no backup result.""" - operation = BackupAwareOperation(self.backup_manager) - - # Test rollback with None backup result - rollback_success = operation.rollback_on_failure(None, self.test_file, "lmstudio") - self.assertFalse(rollback_success) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_backup_integration.py b/tests/test_mcp_backup_integration.py deleted file mode 100644 index 8cc0dec..0000000 --- a/tests/test_mcp_backup_integration.py +++ /dev/null @@ -1,308 +0,0 @@ -"""Tests for MCP backup system integration. - -This module contains integration tests for the backup system with existing -Hatch infrastructure and end-to-end workflows. -""" - -import unittest -import tempfile -import shutil -import json -import time -from pathlib import Path -from unittest.mock import Mock, patch - -from wobble.decorators import integration_test, slow_test, regression_test -from test_data_utils import MCPBackupTestDataLoader - -from hatch.mcp_host_config.backup import ( - MCPHostConfigBackupManager, - BackupAwareOperation, - BackupInfo, - BackupResult -) - - -class TestMCPBackupIntegration(unittest.TestCase): - """Test backup system integration with existing Hatch infrastructure.""" - - def setUp(self): - """Set up integration test environment.""" - self.temp_dir = Path(tempfile.mkdtemp(prefix="test_integration_")) - self.backup_manager = MCPHostConfigBackupManager(backup_root=self.temp_dir / "backups") - self.test_data = MCPBackupTestDataLoader() - - # Create test configuration files - self.config_dir = self.temp_dir / "configs" - self.config_dir.mkdir(parents=True) - - self.test_configs = {} - for hostname in ['claude-desktop', 'claude-code', 'vscode', 'cursor']: - config_data = self.test_data.load_host_agnostic_config("simple_server") - config_file = self.config_dir / f"{hostname}_config.json" - with open(config_file, 'w') as f: - json.dump(config_data, f, indent=2) - self.test_configs[hostname] = config_file - - def tearDown(self): - """Clean up integration test environment.""" - shutil.rmtree(self.temp_dir, ignore_errors=True) - - @integration_test(scope="component") - def test_complete_backup_restore_cycle(self): - """Test complete backup creation and restoration cycle.""" - hostname = 'claude-desktop' - config_file = self.test_configs[hostname] - - # Create backup - backup_result = self.backup_manager.create_backup(config_file, hostname) - self.assertTrue(backup_result.success) - - # Modify original file - modified_data = self.test_data.load_host_agnostic_config("complex_server") - with open(config_file, 'w') as f: - json.dump(modified_data, f) - - # Verify file was modified - with open(config_file) as f: - current_data = json.load(f) - self.assertEqual(current_data, modified_data) - - # Restore from backup (placeholder - actual restore would need host config paths) - restore_success = self.backup_manager.restore_backup(hostname) - self.assertTrue(restore_success) # Currently returns True as placeholder - - @integration_test(scope="component") - def test_multi_host_backup_management(self): - """Test backup management across multiple hosts.""" - # Create backups for multiple hosts - results = {} - for hostname, config_file in self.test_configs.items(): - results[hostname] = self.backup_manager.create_backup(config_file, hostname) - self.assertTrue(results[hostname].success) - - # Verify separate backup directories - for hostname in self.test_configs.keys(): - backups = self.backup_manager.list_backups(hostname) - self.assertEqual(len(backups), 1) - - # Verify backup isolation - backup_dir = backups[0].file_path.parent - self.assertEqual(backup_dir.name, hostname) - - # Verify no cross-contamination - for other_hostname in self.test_configs.keys(): - if other_hostname != hostname: - other_backups = self.backup_manager.list_backups(other_hostname) - self.assertNotEqual( - backups[0].file_path.parent, - other_backups[0].file_path.parent - ) - - @integration_test(scope="end_to_end") - def test_backup_with_configuration_update_workflow(self): - """Test backup integration with configuration update operations.""" - hostname = 'vscode' - config_file = self.test_configs[hostname] - - # Simulate configuration update with backup - original_data = self.test_data.load_host_agnostic_config("simple_server") - updated_data = self.test_data.load_host_agnostic_config("complex_server") - - # Ensure original data is in file - with open(config_file, 'w') as f: - json.dump(original_data, f) - - # Simulate update operation with backup - backup_result = self.backup_manager.create_backup(config_file, hostname) - self.assertTrue(backup_result.success) - - # Update configuration - with open(config_file, 'w') as f: - json.dump(updated_data, f) - - # Verify backup contains original data - backups = self.backup_manager.list_backups(hostname) - self.assertEqual(len(backups), 1) - - with open(backups[0].file_path) as f: - backup_data = json.load(f) - self.assertEqual(backup_data, original_data) - - # Verify current file has updated data - with open(config_file) as f: - current_data = json.load(f) - self.assertEqual(current_data, updated_data) - - @integration_test(scope="service") - def test_backup_system_with_existing_test_utilities(self): - """Test backup system integration with existing test utilities.""" - # Use existing TestDataLoader patterns - test_config = self.test_data.load_host_agnostic_config("complex_server") - - # Test backup creation with complex configuration - config_path = self.temp_dir / "complex_config.json" - with open(config_path, 'w') as f: - json.dump(test_config, f) - - result = self.backup_manager.create_backup(config_path, "lmstudio") - self.assertTrue(result.success) - - # Verify integration with existing test data patterns - self.assertIsInstance(test_config, dict) - self.assertIn("servers", test_config) - - # Verify backup content matches test data - with open(result.backup_path) as f: - backup_content = json.load(f) - self.assertEqual(backup_content, test_config) - - @integration_test(scope="component") - def test_backup_aware_operation_workflow(self): - """Test backup-aware operation following environment manager patterns.""" - hostname = 'cursor' - config_file = self.test_configs[hostname] - - # Test backup-aware operation following existing patterns - operation = BackupAwareOperation(self.backup_manager) - - # Simulate environment manager update workflow - backup_result = operation.prepare_backup(config_file, hostname, no_backup=False) - self.assertTrue(backup_result.success) - - # Verify backup was created following existing patterns - backups = self.backup_manager.list_backups(hostname) - self.assertEqual(len(backups), 1) - self.assertEqual(backups[0].hostname, hostname) - - # Test rollback capability - rollback_success = operation.rollback_on_failure(backup_result, config_file, hostname) - self.assertTrue(rollback_success) - - -class TestMCPBackupPerformance(unittest.TestCase): - """Test backup system performance characteristics.""" - - def setUp(self): - """Set up performance test environment.""" - self.temp_dir = Path(tempfile.mkdtemp(prefix="test_performance_")) - self.backup_manager = MCPHostConfigBackupManager(backup_root=self.temp_dir / "backups") - self.test_data = MCPBackupTestDataLoader() - - def tearDown(self): - """Clean up performance test environment.""" - shutil.rmtree(self.temp_dir, ignore_errors=True) - - @slow_test - @regression_test - def test_backup_performance_large_config(self): - """Test backup performance with larger configuration files.""" - # Create large host-agnostic configuration - large_config = {"servers": {}} - for i in range(1000): - large_config["servers"][f"server_{i}"] = { - "command": f"python_{i}", - "args": [f"arg_{j}" for j in range(10)] - } - - config_file = self.temp_dir / "large_config.json" - with open(config_file, 'w') as f: - json.dump(large_config, f) - - start_time = time.time() - result = self.backup_manager.create_backup(config_file, "gemini") - duration = time.time() - start_time - - self.assertTrue(result.success) - self.assertLess(duration, 1.0) # Should complete within 1 second - - @regression_test - def test_pydantic_validation_performance(self): - """Test Pydantic model validation performance.""" - hostname = "claude-desktop" - config_data = self.test_data.load_host_agnostic_config("simple_server") - config_file = self.temp_dir / "test_config.json" - - with open(config_file, 'w') as f: - json.dump(config_data, f) - - start_time = time.time() - - # Create backup (includes Pydantic validation) - result = self.backup_manager.create_backup(config_file, hostname) - - # List backups (includes Pydantic model creation) - backups = self.backup_manager.list_backups(hostname) - - duration = time.time() - start_time - - self.assertTrue(result.success) - self.assertEqual(len(backups), 1) - self.assertLess(duration, 0.1) # Pydantic operations should be fast - - @regression_test - def test_concurrent_backup_operations(self): - """Test concurrent backup operations for different hosts.""" - import threading - - results = {} - config_files = {} - - # Create test configurations for different hosts - for hostname in ['claude-desktop', 'vscode', 'cursor', 'lmstudio']: - config_data = self.test_data.load_host_agnostic_config("simple_server") - config_file = self.temp_dir / f"{hostname}_config.json" - with open(config_file, 'w') as f: - json.dump(config_data, f) - config_files[hostname] = config_file - - def create_backup_thread(hostname, config_file): - results[hostname] = self.backup_manager.create_backup(config_file, hostname) - - # Start concurrent backup operations - threads = [] - for hostname, config_file in config_files.items(): - thread = threading.Thread(target=create_backup_thread, args=(hostname, config_file)) - threads.append(thread) - thread.start() - - # Wait for all threads to complete - for thread in threads: - thread.join(timeout=5.0) - - # Verify all operations succeeded - for hostname in config_files.keys(): - self.assertIn(hostname, results) - self.assertTrue(results[hostname].success) - - @regression_test - def test_backup_list_performance_many_backups(self): - """Test backup listing performance with many backup files.""" - hostname = "claude-code" - config_data = self.test_data.load_host_agnostic_config("simple_server") - config_file = self.temp_dir / "test_config.json" - - with open(config_file, 'w') as f: - json.dump(config_data, f) - - # Create many backups - for i in range(50): - result = self.backup_manager.create_backup(config_file, hostname) - self.assertTrue(result.success) - - # Test listing performance - start_time = time.time() - backups = self.backup_manager.list_backups(hostname) - duration = time.time() - start_time - - self.assertEqual(len(backups), 50) - self.assertLess(duration, 0.1) # Should be fast even with many backups - - # Verify all backups are valid Pydantic models - for backup in backups: - self.assertIsInstance(backup, BackupInfo) - self.assertEqual(backup.hostname, hostname) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_cli_all_host_specific_args.py b/tests/test_mcp_cli_all_host_specific_args.py deleted file mode 100644 index 86f7092..0000000 --- a/tests/test_mcp_cli_all_host_specific_args.py +++ /dev/null @@ -1,496 +0,0 @@ -""" -Tests for ALL host-specific CLI arguments in MCP configure command. - -This module tests that: -1. All host-specific arguments are accepted for all hosts -2. Unsupported fields are reported as "UNSUPPORTED" in conversion reports -3. All new arguments (httpUrl, includeTools, excludeTools, inputs) work correctly -""" - -import unittest -from unittest.mock import patch, MagicMock -from io import StringIO - -from hatch.cli_hatch import handle_mcp_configure, parse_input -from hatch.mcp_host_config import MCPHostType -from hatch.mcp_host_config.models import ( - MCPServerConfigGemini, MCPServerConfigCursor, MCPServerConfigVSCode, - MCPServerConfigClaude, MCPServerConfigCodex -) - - -class TestAllGeminiArguments(unittest.TestCase): - """Test ALL Gemini-specific CLI arguments.""" - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_all_gemini_arguments_accepted(self, mock_stdout, mock_manager_class): - """Test that all Gemini arguments are accepted and passed to model.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command='python', - args=['server.py'], - timeout=30000, - trust=True, - cwd='/workspace', - http_url='https://api.example.com/mcp', - include_tools=['tool1', 'tool2'], - exclude_tools=['dangerous_tool'], - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify all fields were passed to Gemini model - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertIsInstance(server_config, MCPServerConfigGemini) - self.assertEqual(server_config.timeout, 30000) - self.assertEqual(server_config.trust, True) - self.assertEqual(server_config.cwd, '/workspace') - self.assertEqual(server_config.httpUrl, 'https://api.example.com/mcp') - self.assertEqual(server_config.includeTools, ['tool1', 'tool2']) - self.assertEqual(server_config.excludeTools, ['dangerous_tool']) - - -class TestUnsupportedFieldReporting(unittest.TestCase): - """Test that unsupported fields are reported correctly, not rejected.""" - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_gemini_args_on_vscode_show_unsupported(self, mock_stdout, mock_manager_class): - """Test that Gemini-specific args on VS Code show as UNSUPPORTED.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='vscode', - server_name='test-server', - command='python', - args=['server.py'], - timeout=30000, # Gemini-only field - trust=True, # Gemini-only field - auto_approve=True - ) - - # Should succeed (not return error code 1) - self.assertEqual(result, 0) - - # Check that output contains "UNSUPPORTED" for Gemini fields - output = mock_stdout.getvalue() - self.assertIn('UNSUPPORTED', output) - self.assertIn('timeout', output) - self.assertIn('trust', output) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_vscode_inputs_on_gemini_show_unsupported(self, mock_stdout, mock_manager_class): - """Test that VS Code inputs on Gemini show as UNSUPPORTED.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command='python', - args=['server.py'], - input=['promptString,api-key,API Key,password=true'], # VS Code-only field - auto_approve=True - ) - - # Should succeed (not return error code 1) - self.assertEqual(result, 0) - - # Check that output contains "UNSUPPORTED" for inputs field - output = mock_stdout.getvalue() - self.assertIn('UNSUPPORTED', output) - self.assertIn('inputs', output) - - -class TestVSCodeInputsParsing(unittest.TestCase): - """Test VS Code inputs parsing.""" - - def test_parse_input_basic(self): - """Test basic input parsing.""" - input_list = ['promptString,api-key,GitHub Personal Access Token'] - result = parse_input(input_list) - - self.assertIsNotNone(result) - self.assertEqual(len(result), 1) - self.assertEqual(result[0]['type'], 'promptString') - self.assertEqual(result[0]['id'], 'api-key') - self.assertEqual(result[0]['description'], 'GitHub Personal Access Token') - self.assertNotIn('password', result[0]) - - def test_parse_input_with_password(self): - """Test input parsing with password flag.""" - input_list = ['promptString,api-key,API Key,password=true'] - result = parse_input(input_list) - - self.assertIsNotNone(result) - self.assertEqual(len(result), 1) - self.assertEqual(result[0]['password'], True) - - def test_parse_input_multiple(self): - """Test parsing multiple inputs.""" - input_list = [ - 'promptString,api-key,API Key,password=true', - 'promptString,db-url,Database URL' - ] - result = parse_input(input_list) - - self.assertIsNotNone(result) - self.assertEqual(len(result), 2) - - def test_parse_input_none(self): - """Test parsing None inputs.""" - result = parse_input(None) - self.assertIsNone(result) - - def test_parse_input_empty(self): - """Test parsing empty inputs list.""" - result = parse_input([]) - self.assertIsNone(result) - - -class TestVSCodeInputsIntegration(unittest.TestCase): - """Test VS Code inputs integration with configure command.""" - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - def test_vscode_inputs_passed_to_model(self, mock_manager_class): - """Test that parsed inputs are passed to VS Code model.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='vscode', - server_name='test-server', - command='python', - args=['server.py'], - input=['promptString,api-key,API Key,password=true'], - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify inputs were passed to VS Code model - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertIsInstance(server_config, MCPServerConfigVSCode) - self.assertIsNotNone(server_config.inputs) - self.assertEqual(len(server_config.inputs), 1) - self.assertEqual(server_config.inputs[0]['id'], 'api-key') - - -class TestHttpUrlArgument(unittest.TestCase): - """Test --http-url argument for Gemini.""" - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - def test_http_url_passed_to_gemini(self, mock_manager_class): - """Test that httpUrl is passed to Gemini model.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command='python', - args=['server.py'], - http_url='https://api.example.com/mcp', - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify httpUrl was passed to Gemini model - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertIsInstance(server_config, MCPServerConfigGemini) - self.assertEqual(server_config.httpUrl, 'https://api.example.com/mcp') - - -class TestToolFilteringArguments(unittest.TestCase): - """Test --include-tools and --exclude-tools arguments for Gemini.""" - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - def test_include_tools_passed_to_gemini(self, mock_manager_class): - """Test that includeTools is passed to Gemini model.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command='python', - args=['server.py'], - include_tools=['tool1', 'tool2', 'tool3'], - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify includeTools was passed to Gemini model - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertIsInstance(server_config, MCPServerConfigGemini) - self.assertEqual(server_config.includeTools, ['tool1', 'tool2', 'tool3']) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - def test_exclude_tools_passed_to_gemini(self, mock_manager_class): - """Test that excludeTools is passed to Gemini model.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command='python', - args=['server.py'], - exclude_tools=['dangerous_tool'], - auto_approve=True - ) - - self.assertEqual(result, 0) - - # Verify excludeTools was passed to Gemini model - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertIsInstance(server_config, MCPServerConfigGemini) - self.assertEqual(server_config.excludeTools, ['dangerous_tool']) - - -class TestAllCodexArguments(unittest.TestCase): - """Test ALL Codex-specific CLI arguments.""" - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_all_codex_arguments_accepted(self, mock_stdout, mock_manager_class): - """Test that all Codex arguments are accepted and passed to model.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - # Test STDIO server with Codex-specific STDIO fields - result = handle_mcp_configure( - host='codex', - server_name='test-server', - command='npx', - args=['-y', '@upstash/context7-mcp'], - env_vars=['PATH', 'HOME'], - cwd='/workspace', - startup_timeout=15, - tool_timeout=120, - enabled=True, - include_tools=['read', 'write'], - exclude_tools=['delete'], - auto_approve=True - ) - - # Verify success - self.assertEqual(result, 0) - - # Verify configure_server was called - mock_manager.configure_server.assert_called_once() - - # Verify server_config is MCPServerConfigCodex - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertIsInstance(server_config, MCPServerConfigCodex) - - # Verify Codex-specific STDIO fields - self.assertEqual(server_config.env_vars, ['PATH', 'HOME']) - self.assertEqual(server_config.cwd, '/workspace') - self.assertEqual(server_config.startup_timeout_sec, 15) - self.assertEqual(server_config.tool_timeout_sec, 120) - self.assertTrue(server_config.enabled) - self.assertEqual(server_config.enabled_tools, ['read', 'write']) - self.assertEqual(server_config.disabled_tools, ['delete']) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_codex_env_vars_list(self, mock_stdout, mock_manager_class): - """Test that env_vars accepts multiple values as a list.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='codex', - server_name='test-server', - command='npx', - args=['-y', 'package'], - env_vars=['PATH', 'HOME', 'USER'], - auto_approve=True - ) - - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertEqual(server_config.env_vars, ['PATH', 'HOME', 'USER']) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_codex_env_header_parsing(self, mock_stdout, mock_manager_class): - """Test that env_header parses KEY=ENV_VAR format correctly.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='codex', - server_name='test-server', - command='npx', - args=['-y', 'package'], - env_header=['X-API-Key=API_KEY', 'Authorization=AUTH_TOKEN'], - auto_approve=True - ) - - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertEqual(server_config.env_http_headers, { - 'X-API-Key': 'API_KEY', - 'Authorization': 'AUTH_TOKEN' - }) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_codex_timeout_fields(self, mock_stdout, mock_manager_class): - """Test that timeout fields are passed as integers.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='codex', - server_name='test-server', - command='npx', - args=['-y', 'package'], - startup_timeout=30, - tool_timeout=180, - auto_approve=True - ) - - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertEqual(server_config.startup_timeout_sec, 30) - self.assertEqual(server_config.tool_timeout_sec, 180) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_codex_enabled_flag(self, mock_stdout, mock_manager_class): - """Test that enabled flag works as boolean.""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='codex', - server_name='test-server', - command='npx', - args=['-y', 'package'], - enabled=True, - auto_approve=True - ) - - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertTrue(server_config.enabled) - - @patch('hatch.cli_hatch.MCPHostConfigurationManager') - @patch('sys.stdout', new_callable=StringIO) - def test_codex_reuses_shared_arguments(self, mock_stdout, mock_manager_class): - """Test that Codex reuses shared arguments (cwd, include-tools, exclude-tools).""" - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_manager.configure_server.return_value = mock_result - - result = handle_mcp_configure( - host='codex', - server_name='test-server', - command='npx', - args=['-y', 'package'], - cwd='/workspace', - include_tools=['tool1', 'tool2'], - exclude_tools=['tool3'], - auto_approve=True - ) - - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - - # Verify shared arguments work for Codex STDIO servers - self.assertEqual(server_config.cwd, '/workspace') - self.assertEqual(server_config.enabled_tools, ['tool1', 'tool2']) - self.assertEqual(server_config.disabled_tools, ['tool3']) - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/test_mcp_cli_backup_management.py b/tests/test_mcp_cli_backup_management.py deleted file mode 100644 index 6050b57..0000000 --- a/tests/test_mcp_cli_backup_management.py +++ /dev/null @@ -1,295 +0,0 @@ -""" -Test suite for MCP CLI backup management commands (Phase 3d). - -This module tests the new MCP backup management functionality: -- hatch mcp backup restore -- hatch mcp backup list -- hatch mcp backup clean - -Tests cover argument parsing, backup operations, output formatting, -and error handling scenarios. -""" - -import unittest -from unittest.mock import patch, MagicMock, ANY -import sys -from pathlib import Path -from datetime import datetime - -# Add the parent directory to the path to import hatch modules -sys.path.insert(0, str(Path(__file__).parent.parent)) - -from hatch.cli_hatch import ( - main, handle_mcp_backup_restore, handle_mcp_backup_list, handle_mcp_backup_clean -) -from hatch.mcp_host_config.models import MCPHostType -from wobble import regression_test, integration_test - - -class TestMCPBackupRestoreCommand(unittest.TestCase): - """Test suite for MCP backup restore command.""" - - @regression_test - def test_backup_restore_argument_parsing(self): - """Test argument parsing for 'hatch mcp backup restore' command.""" - test_args = ['hatch', 'mcp', 'backup', 'restore', 'claude-desktop', '--backup-file', 'test.backup'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_backup_restore', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with( - ANY, 'claude-desktop', 'test.backup', False, False - ) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @regression_test - def test_backup_restore_dry_run_argument(self): - """Test dry run argument for backup restore command.""" - test_args = ['hatch', 'mcp', 'backup', 'restore', 'cursor', '--dry-run', '--auto-approve'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_backup_restore', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with( - ANY, 'cursor', None, True, True - ) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @integration_test(scope="component") - def test_backup_restore_invalid_host(self): - """Test backup restore with invalid host type.""" - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_restore(mock_env_manager.return_value, 'invalid-host') - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: Invalid host 'invalid-host'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_backup_restore_no_backups(self): - """Test backup restore when no backups exist.""" - with patch('hatch.mcp_host_config.backup.MCPHostConfigBackupManager') as mock_backup_class: - mock_backup_manager = MagicMock() - mock_backup_manager._get_latest_backup.return_value = None - mock_backup_class.return_value = mock_backup_manager - - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_restore(mock_env_manager.return_value, 'claude-desktop') - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: No backups found for host 'claude-desktop'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_backup_restore_dry_run(self): - """Test backup restore dry run functionality.""" - with patch('hatch.mcp_host_config.backup.MCPHostConfigBackupManager') as mock_backup_class: - mock_backup_manager = MagicMock() - mock_backup_path = Path("/test/backup.json") - mock_backup_manager._get_latest_backup.return_value = mock_backup_path - mock_backup_class.return_value = mock_backup_manager - - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_restore(mock_env_manager.return_value, 'claude-desktop', dry_run=True) - - self.assertEqual(result, 0) - - # Verify dry run output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[DRY RUN] Would restore backup for host 'claude-desktop'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_backup_restore_successful(self): - """Test successful backup restore operation.""" - with patch('hatch.mcp_host_config.backup.MCPHostConfigBackupManager') as mock_backup_class: - mock_backup_manager = MagicMock() - mock_backup_path = Path("/test/backup.json") - mock_backup_manager._get_latest_backup.return_value = mock_backup_path - mock_backup_manager.restore_backup.return_value = True - mock_backup_class.return_value = mock_backup_manager - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_restore(mock_env_manager.return_value, 'claude-desktop', auto_approve=True) - - self.assertEqual(result, 0) - mock_backup_manager.restore_backup.assert_called_once() - - # Verify success message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[SUCCESS] Successfully restored backup" in call for call in print_calls)) - - -class TestMCPBackupListCommand(unittest.TestCase): - """Test suite for MCP backup list command.""" - - @regression_test - def test_backup_list_argument_parsing(self): - """Test argument parsing for 'hatch mcp backup list' command.""" - test_args = ['hatch', 'mcp', 'backup', 'list', 'vscode', '--detailed'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_backup_list', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with('vscode', True) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @integration_test(scope="component") - def test_backup_list_invalid_host(self): - """Test backup list with invalid host type.""" - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_list('invalid-host') - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: Invalid host 'invalid-host'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_backup_list_no_backups(self): - """Test backup list when no backups exist.""" - with patch('hatch.mcp_host_config.backup.MCPHostConfigBackupManager') as mock_backup_class: - mock_backup_manager = MagicMock() - mock_backup_manager.list_backups.return_value = [] - mock_backup_class.return_value = mock_backup_manager - - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_list('claude-desktop') - - self.assertEqual(result, 0) - - # Verify no backups message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("No backups found for host 'claude-desktop'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_backup_list_detailed_output(self): - """Test backup list with detailed output format.""" - from hatch.mcp_host_config.backup import BackupInfo - - # Create mock backup info with proper attributes - mock_backup = MagicMock(spec=BackupInfo) - mock_backup.file_path = MagicMock() - mock_backup.file_path.name = "mcp.json.claude-desktop.20250922_143000_123456" - mock_backup.timestamp = datetime(2025, 9, 22, 14, 30, 0) - mock_backup.file_size = 1024 - mock_backup.age_days = 5 - - with patch('hatch.mcp_host_config.backup.MCPHostConfigBackupManager') as mock_backup_class: - mock_backup_manager = MagicMock() - mock_backup_manager.list_backups.return_value = [mock_backup] - mock_backup_class.return_value = mock_backup_manager - - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_list('claude-desktop', detailed=True) - - self.assertEqual(result, 0) - - # Verify detailed table output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Backup File" in call for call in print_calls)) - self.assertTrue(any("Created" in call for call in print_calls)) - self.assertTrue(any("Size" in call for call in print_calls)) - - -class TestMCPBackupCleanCommand(unittest.TestCase): - """Test suite for MCP backup clean command.""" - - @regression_test - def test_backup_clean_argument_parsing(self): - """Test argument parsing for 'hatch mcp backup clean' command.""" - test_args = ['hatch', 'mcp', 'backup', 'clean', 'cursor', '--older-than-days', '30', '--dry-run'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_backup_clean', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with('cursor', 30, None, True, False) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @integration_test(scope="component") - def test_backup_clean_no_criteria(self): - """Test backup clean with no cleanup criteria specified.""" - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_clean('claude-desktop') - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: Must specify either --older-than-days or --keep-count" in call for call in print_calls)) - - @integration_test(scope="component") - def test_backup_clean_dry_run(self): - """Test backup clean dry run functionality.""" - from hatch.mcp_host_config.backup import BackupInfo - - # Create mock backup info with proper attributes - mock_backup = MagicMock(spec=BackupInfo) - mock_backup.file_path = Path("/test/old_backup.json") - mock_backup.age_days = 35 - - with patch('hatch.mcp_host_config.backup.MCPHostConfigBackupManager') as mock_backup_class: - mock_backup_manager = MagicMock() - mock_backup_manager.list_backups.return_value = [mock_backup] - mock_backup_class.return_value = mock_backup_manager - - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_clean('claude-desktop', older_than_days=30, dry_run=True) - - self.assertEqual(result, 0) - - # Verify dry run output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[DRY RUN] Would clean" in call for call in print_calls)) - - @integration_test(scope="component") - def test_backup_clean_successful(self): - """Test successful backup clean operation.""" - from hatch.mcp_host_config.backup import BackupInfo - - # Create mock backup with proper attributes - mock_backup = MagicMock(spec=BackupInfo) - mock_backup.file_path = Path("/test/backup.json") - mock_backup.age_days = 35 - - with patch('hatch.mcp_host_config.backup.MCPHostConfigBackupManager') as mock_backup_class: - mock_backup_manager = MagicMock() - mock_backup_manager.list_backups.return_value = [mock_backup] # Some backups exist - mock_backup_manager.clean_backups.return_value = 3 # 3 backups cleaned - mock_backup_class.return_value = mock_backup_manager - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - with patch('builtins.print') as mock_print: - result = handle_mcp_backup_clean('claude-desktop', older_than_days=30, auto_approve=True) - - self.assertEqual(result, 0) - mock_backup_manager.clean_backups.assert_called_once() - - # Verify success message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("βœ“ Successfully cleaned 3 backup(s)" in call for call in print_calls)) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_cli_direct_management.py b/tests/test_mcp_cli_direct_management.py deleted file mode 100644 index d22270f..0000000 --- a/tests/test_mcp_cli_direct_management.py +++ /dev/null @@ -1,456 +0,0 @@ -""" -Test suite for MCP CLI direct management commands (Phase 3e). - -This module tests the new MCP direct management functionality: -- hatch mcp configure -- hatch mcp remove - -Tests cover argument parsing, server configuration, output formatting, -and error handling scenarios. -""" - -import unittest -from unittest.mock import patch, MagicMock, ANY -import sys -from pathlib import Path - -# Add the parent directory to the path to import hatch modules -sys.path.insert(0, str(Path(__file__).parent.parent)) - -from hatch.cli_hatch import ( - main, handle_mcp_configure, handle_mcp_remove, handle_mcp_remove_server, - handle_mcp_remove_host, parse_env_vars, parse_header -) -from hatch.mcp_host_config.models import MCPHostType, MCPServerConfig -from wobble import regression_test, integration_test - - -class TestMCPConfigureCommand(unittest.TestCase): - """Test suite for MCP configure command.""" - - @regression_test - def test_configure_argument_parsing_basic(self): - """Test basic argument parsing for 'hatch mcp configure' command.""" - # Updated to match current CLI: server_name is positional, --host is required, --command/--url are mutually exclusive - test_args = ['hatch', 'mcp', 'configure', 'weather-server', '--host', 'claude-desktop', '--command', 'python', '--args', 'weather.py'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_configure', return_value=0) as mock_handler: - try: - result = main() - # If main() returns without SystemExit, check the handler was called - # Updated to include ALL host-specific parameters (27 total) - mock_handler.assert_called_once_with( - 'claude-desktop', 'weather-server', 'python', ['weather.py'], - None, None, None, None, False, None, None, None, None, None, None, - False, None, None, None, None, None, False, None, None, False, False, False - ) - except SystemExit as e: - # If SystemExit is raised, it should be 0 (success) and handler should have been called - if e.code == 0: - mock_handler.assert_called_once_with( - 'claude-desktop', 'weather-server', 'python', ['weather.py'], - None, None, None, None, False, None, None, None, None, None, None, - False, None, None, None, None, None, False, None, None, False, False, False - ) - else: - self.fail(f"main() exited with code {e.code}, expected 0") - - @regression_test - def test_configure_argument_parsing_with_options(self): - """Test argument parsing with environment variables and options.""" - test_args = [ - 'hatch', 'mcp', 'configure', 'file-server', '--host', 'cursor', '--url', 'http://localhost:8080', - '--env-var', 'API_KEY=secret', '--env-var', 'DEBUG=true', - '--header', 'Authorization=Bearer token', - '--no-backup', '--dry-run', '--auto-approve' - ] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_configure', return_value=0) as mock_handler: - try: - main() - # Updated to include ALL host-specific parameters (27 total) - mock_handler.assert_called_once_with( - 'cursor', 'file-server', None, None, - ['API_KEY=secret', 'DEBUG=true'], 'http://localhost:8080', - ['Authorization=Bearer token'], None, False, None, None, None, None, None, None, - False, None, None, None, None, None, False, None, None, True, True, True - ) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @regression_test - def test_parse_env_vars(self): - """Test environment variable parsing utility.""" - # Valid environment variables - env_list = ['API_KEY=secret', 'DEBUG=true', 'PORT=8080'] - result = parse_env_vars(env_list) - - expected = { - 'API_KEY': 'secret', - 'DEBUG': 'true', - 'PORT': '8080' - } - self.assertEqual(result, expected) - - # Empty list - self.assertEqual(parse_env_vars(None), {}) - self.assertEqual(parse_env_vars([]), {}) - - # Invalid format (should be skipped with warning) - with patch('builtins.print') as mock_print: - result = parse_env_vars(['INVALID_FORMAT', 'VALID=value']) - self.assertEqual(result, {'VALID': 'value'}) - mock_print.assert_called() - - @regression_test - def test_parse_header(self): - """Test HTTP headers parsing utility.""" - # Valid headers - headers_list = ['Authorization=Bearer token', 'Content-Type=application/json'] - result = parse_header(headers_list) - - expected = { - 'Authorization': 'Bearer token', - 'Content-Type': 'application/json' - } - self.assertEqual(result, expected) - - # Empty list - self.assertEqual(parse_header(None), {}) - self.assertEqual(parse_header([]), {}) - - @integration_test(scope="component") - def test_configure_invalid_host(self): - """Test configure command with invalid host type.""" - with patch('builtins.print') as mock_print: - result = handle_mcp_configure('invalid-host', 'test-server', 'python', ['test.py']) - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: Invalid host 'invalid-host'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_configure_dry_run(self): - """Test configure command dry run functionality.""" - with patch('builtins.print') as mock_print: - result = handle_mcp_configure( - 'claude-desktop', 'weather-server', 'python', ['weather.py'], - env=['API_KEY=secret'], url=None, - dry_run=True - ) - - self.assertEqual(result, 0) - - # Verify dry run output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[DRY RUN] Would configure MCP server 'weather-server'" in call for call in print_calls)) - self.assertTrue(any("[DRY RUN] Command: python" in call for call in print_calls)) - self.assertTrue(any("[DRY RUN] Environment:" in call for call in print_calls)) - # URL should not be present for local server configuration - - @integration_test(scope="component") - def test_configure_successful(self): - """Test successful MCP server configuration.""" - from hatch.mcp_host_config.host_management import ConfigurationResult - - mock_result = ConfigurationResult( - success=True, - hostname='claude-desktop', - server_name='weather-server', - backup_path=Path('/test/backup.json') - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager.configure_server.return_value = mock_result - mock_manager_class.return_value = mock_manager - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - with patch('builtins.print') as mock_print: - result = handle_mcp_configure( - 'claude-desktop', 'weather-server', 'python', ['weather.py'], - auto_approve=True - ) - - self.assertEqual(result, 0) - mock_manager.configure_server.assert_called_once() - - # Verify success message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[SUCCESS] Successfully configured MCP server 'weather-server'" in call for call in print_calls)) - self.assertTrue(any("Backup created:" in call for call in print_calls)) - - @integration_test(scope="component") - def test_configure_failed(self): - """Test failed MCP server configuration.""" - from hatch.mcp_host_config.host_management import ConfigurationResult - - mock_result = ConfigurationResult( - success=False, - hostname='claude-desktop', - server_name='weather-server', - error_message='Configuration validation failed' - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager.configure_server.return_value = mock_result - mock_manager_class.return_value = mock_manager - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - with patch('builtins.print') as mock_print: - result = handle_mcp_configure( - 'claude-desktop', 'weather-server', 'python', ['weather.py'], - auto_approve=True - ) - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[ERROR] Failed to configure MCP server 'weather-server'" in call for call in print_calls)) - self.assertTrue(any("Configuration validation failed" in call for call in print_calls)) - - -class TestMCPRemoveCommand(unittest.TestCase): - """Test suite for MCP remove command.""" - - @regression_test - def test_remove_argument_parsing(self): - """Test argument parsing for 'hatch mcp remove server' command.""" - test_args = ['hatch', 'mcp', 'remove', 'server', 'old-server', '--host', 'vscode', '--no-backup', '--auto-approve'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_remove_server', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with(ANY, 'old-server', 'vscode', None, True, False, True) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @integration_test(scope="component") - def test_remove_invalid_host(self): - """Test remove command with invalid host type.""" - with patch('builtins.print') as mock_print: - result = handle_mcp_remove('invalid-host', 'test-server') - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: Invalid host 'invalid-host'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_remove_dry_run(self): - """Test remove command dry run functionality.""" - with patch('builtins.print') as mock_print: - result = handle_mcp_remove('claude-desktop', 'old-server', no_backup=True, dry_run=True) - - self.assertEqual(result, 0) - - # Verify dry run output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[DRY RUN] Would remove MCP server 'old-server'" in call for call in print_calls)) - self.assertTrue(any("[DRY RUN] Backup: Disabled" in call for call in print_calls)) - - @integration_test(scope="component") - def test_remove_successful(self): - """Test successful MCP server removal.""" - from hatch.mcp_host_config.host_management import ConfigurationResult - - mock_result = ConfigurationResult( - success=True, - hostname='claude-desktop', - server_name='old-server', - backup_path=Path('/test/backup.json') - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager.remove_server.return_value = mock_result - mock_manager_class.return_value = mock_manager - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - with patch('builtins.print') as mock_print: - result = handle_mcp_remove('claude-desktop', 'old-server', auto_approve=True) - - self.assertEqual(result, 0) - mock_manager.remove_server.assert_called_once() - - # Verify success message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[SUCCESS] Successfully removed MCP server 'old-server'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_remove_failed(self): - """Test failed MCP server removal.""" - from hatch.mcp_host_config.host_management import ConfigurationResult - - mock_result = ConfigurationResult( - success=False, - hostname='claude-desktop', - server_name='old-server', - error_message='Server not found in configuration' - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager.remove_server.return_value = mock_result - mock_manager_class.return_value = mock_manager - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - with patch('builtins.print') as mock_print: - result = handle_mcp_remove('claude-desktop', 'old-server', auto_approve=True) - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[ERROR] Failed to remove MCP server 'old-server'" in call for call in print_calls)) - self.assertTrue(any("Server not found in configuration" in call for call in print_calls)) - - -class TestMCPRemoveServerCommand(unittest.TestCase): - """Test suite for MCP remove server command (new object-action pattern).""" - - @regression_test - def test_remove_server_argument_parsing(self): - """Test argument parsing for 'hatch mcp remove server' command.""" - test_args = ['hatch', 'mcp', 'remove', 'server', 'test-server', '--host', 'claude-desktop', '--no-backup'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_remove_server', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with(ANY, 'test-server', 'claude-desktop', None, True, False, False) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @integration_test(scope="component") - def test_remove_server_multi_host(self): - """Test remove server from multiple hosts.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager.remove_server.return_value = MagicMock(success=True, backup_path=None) - mock_manager_class.return_value = mock_manager - - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_remove_server(mock_env_manager.return_value, 'test-server', 'claude-desktop,cursor', auto_approve=True) - - self.assertEqual(result, 0) - self.assertEqual(mock_manager.remove_server.call_count, 2) - - # Verify success messages - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[SUCCESS] Successfully removed 'test-server' from 'claude-desktop'" in call for call in print_calls)) - self.assertTrue(any("[SUCCESS] Successfully removed 'test-server' from 'cursor'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_remove_server_no_host_specified(self): - """Test remove server with no host specified.""" - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_remove_server(mock_env_manager.return_value, 'test-server') - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: Must specify either --host or --env" in call for call in print_calls)) - - @integration_test(scope="component") - def test_remove_server_dry_run(self): - """Test remove server dry run functionality.""" - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_remove_server(mock_env_manager.return_value, 'test-server', 'claude-desktop', dry_run=True) - - self.assertEqual(result, 0) - - # Verify dry run output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[DRY RUN] Would remove MCP server 'test-server' from hosts: claude-desktop" in call for call in print_calls)) - - -class TestMCPRemoveHostCommand(unittest.TestCase): - """Test suite for MCP remove host command.""" - - @regression_test - def test_remove_host_argument_parsing(self): - """Test argument parsing for 'hatch mcp remove host' command.""" - test_args = ['hatch', 'mcp', 'remove', 'host', 'claude-desktop', '--auto-approve'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_remove_host', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with(ANY, 'claude-desktop', False, False, True) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @integration_test(scope="component") - def test_remove_host_successful(self): - """Test successful host configuration removal.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = Path("/test/backup.json") - mock_manager.remove_host_configuration.return_value = mock_result - mock_manager_class.return_value = mock_manager - - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - # Mock the clear_host_from_all_packages_all_envs method - mock_env_manager.return_value.clear_host_from_all_packages_all_envs.return_value = 2 - - with patch('builtins.print') as mock_print: - result = handle_mcp_remove_host(mock_env_manager.return_value, 'claude-desktop', auto_approve=True) - - self.assertEqual(result, 0) - mock_manager.remove_host_configuration.assert_called_once_with( - hostname='claude-desktop', no_backup=False - ) - - # Verify success message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[SUCCESS] Successfully removed host configuration for 'claude-desktop'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_remove_host_invalid_host(self): - """Test remove host with invalid host type.""" - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_remove_host(mock_env_manager.return_value, 'invalid-host') - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: Invalid host 'invalid-host'" in call for call in print_calls)) - - @integration_test(scope="component") - def test_remove_host_dry_run(self): - """Test remove host dry run functionality.""" - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_manager: - with patch('builtins.print') as mock_print: - result = handle_mcp_remove_host(mock_env_manager.return_value, 'claude-desktop', dry_run=True) - - self.assertEqual(result, 0) - - # Verify dry run output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[DRY RUN] Would remove entire host configuration for 'claude-desktop'" in call for call in print_calls)) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_cli_discovery_listing.py b/tests/test_mcp_cli_discovery_listing.py deleted file mode 100644 index 778a2a4..0000000 --- a/tests/test_mcp_cli_discovery_listing.py +++ /dev/null @@ -1,582 +0,0 @@ -""" -Test suite for MCP CLI discovery and listing commands (Phase 3c). - -This module tests the new MCP discovery and listing functionality: -- hatch mcp discover hosts -- hatch mcp discover servers -- hatch mcp list hosts -- hatch mcp list servers - -Tests cover argument parsing, backend integration, output formatting, -and error handling scenarios. -""" - -import unittest -from unittest.mock import patch, MagicMock -import sys -from pathlib import Path - -# Add the parent directory to the path to import hatch modules -sys.path.insert(0, str(Path(__file__).parent.parent)) - -from hatch.cli_hatch import ( - main, handle_mcp_discover_hosts, handle_mcp_discover_servers, - handle_mcp_list_hosts, handle_mcp_list_servers -) -from hatch.mcp_host_config.models import MCPHostType, MCPServerConfig -from hatch.environment_manager import HatchEnvironmentManager -from wobble import regression_test, integration_test -import json - - -class TestMCPDiscoveryCommands(unittest.TestCase): - """Test suite for MCP discovery commands.""" - - def setUp(self): - """Set up test fixtures.""" - self.mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - self.mock_env_manager.get_current_environment.return_value = "test-env" - self.mock_env_manager.environment_exists.return_value = True - - @regression_test - def test_discover_hosts_argument_parsing(self): - """Test argument parsing for 'hatch mcp discover hosts' command.""" - test_args = ['hatch', 'mcp', 'discover', 'hosts'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_discover_hosts', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once() - except SystemExit as e: - self.assertEqual(e.code, 0) - - @regression_test - def test_discover_servers_argument_parsing(self): - """Test argument parsing for 'hatch mcp discover servers' command.""" - test_args = ['hatch', 'mcp', 'discover', 'servers', '--env', 'test-env'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_discover_servers', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once() - except SystemExit as e: - self.assertEqual(e.code, 0) - - @regression_test - def test_discover_servers_default_environment(self): - """Test discover servers uses current environment when --env not specified.""" - test_args = ['hatch', 'mcp', 'discover', 'servers'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager') as mock_env_class: - mock_env_manager = MagicMock() - mock_env_class.return_value = mock_env_manager - - with patch('hatch.cli_hatch.handle_mcp_discover_servers', return_value=0) as mock_handler: - try: - main() - # Should be called with env_manager and None (default env) - mock_handler.assert_called_once() - args = mock_handler.call_args[0] - self.assertEqual(len(args), 2) # env_manager, env_name - self.assertIsNone(args[1]) # env_name should be None - except SystemExit as e: - self.assertEqual(e.code, 0) - - @integration_test(scope="component") - def test_discover_hosts_backend_integration(self): - """Test discover hosts integration with MCPHostRegistry.""" - with patch('hatch.mcp_host_config.strategies'): # Import strategies - with patch('hatch.cli_hatch.MCPHostRegistry') as mock_registry: - mock_registry.detect_available_hosts.return_value = [ - MCPHostType.CLAUDE_DESKTOP, - MCPHostType.CURSOR - ] - - # Mock strategy for each host type - mock_strategy = MagicMock() - mock_strategy.get_config_path.return_value = Path("/test/config.json") - mock_registry.get_strategy.return_value = mock_strategy - - with patch('builtins.print') as mock_print: - result = handle_mcp_discover_hosts() - - self.assertEqual(result, 0) - mock_registry.detect_available_hosts.assert_called_once() - - # Verify output contains expected information - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Available MCP host platforms:" in call for call in print_calls)) - - @integration_test(scope="component") - def test_discover_servers_backend_integration(self): - """Test discover servers integration with environment manager.""" - # Mock packages with MCP servers - mock_packages = [ - {'name': 'weather-toolkit', 'version': '1.0.0'}, - {'name': 'file-manager', 'version': '2.0.0'}, - {'name': 'regular-package', 'version': '1.5.0'} # No MCP server - ] - - self.mock_env_manager.list_packages.return_value = mock_packages - - # Mock get_package_mcp_server_config to return config for some packages - def mock_get_config(env_manager, env_name, package_name): - if package_name in ['weather-toolkit', 'file-manager']: - return MCPServerConfig( - name=f"{package_name}-server", - command="python", - args=[f"{package_name}.py"], - env={} - ) - else: - raise ValueError(f"Package '{package_name}' has no MCP server") - - with patch('hatch.cli_hatch.get_package_mcp_server_config', side_effect=mock_get_config): - with patch('builtins.print') as mock_print: - result = handle_mcp_discover_servers(self.mock_env_manager, "test-env") - - self.assertEqual(result, 0) - self.mock_env_manager.list_packages.assert_called_once_with("test-env") - - # Verify output contains MCP servers - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("MCP servers in environment 'test-env':" in call for call in print_calls)) - self.assertTrue(any("weather-toolkit-server:" in call for call in print_calls)) - self.assertTrue(any("file-manager-server:" in call for call in print_calls)) - - @regression_test - def test_discover_servers_no_mcp_packages(self): - """Test discover servers when no packages have MCP servers.""" - mock_packages = [ - {'name': 'regular-package-1', 'version': '1.0.0'}, - {'name': 'regular-package-2', 'version': '2.0.0'} - ] - - self.mock_env_manager.list_packages.return_value = mock_packages - - # Mock get_package_mcp_server_config to always raise ValueError - def mock_get_config(env_manager, env_name, package_name): - raise ValueError(f"Package '{package_name}' has no MCP server") - - with patch('hatch.cli_hatch.get_package_mcp_server_config', side_effect=mock_get_config): - with patch('builtins.print') as mock_print: - result = handle_mcp_discover_servers(self.mock_env_manager, "test-env") - - self.assertEqual(result, 0) - - # Verify appropriate message is shown - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("No MCP servers found in environment 'test-env'" in call for call in print_calls)) - - @regression_test - def test_discover_servers_nonexistent_environment(self): - """Test discover servers with nonexistent environment.""" - self.mock_env_manager.environment_exists.return_value = False - - with patch('builtins.print') as mock_print: - result = handle_mcp_discover_servers(self.mock_env_manager, "nonexistent-env") - - self.assertEqual(result, 1) - - # Verify error message - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("Error: Environment 'nonexistent-env' does not exist" in call for call in print_calls)) - - -class TestMCPListCommands(unittest.TestCase): - """Test suite for MCP list commands.""" - - def setUp(self): - """Set up test fixtures.""" - self.mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - self.mock_env_manager.get_current_environment.return_value = "test-env" - self.mock_env_manager.environment_exists.return_value = True - - @regression_test - def test_list_hosts_argument_parsing(self): - """Test argument parsing for 'hatch mcp list hosts' command.""" - test_args = ['hatch', 'mcp', 'list', 'hosts'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_list_hosts', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once() - except SystemExit as e: - self.assertEqual(e.code, 0) - - @regression_test - def test_list_servers_argument_parsing(self): - """Test argument parsing for 'hatch mcp list servers' command.""" - test_args = ['hatch', 'mcp', 'list', 'servers', '--env', 'production'] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_list_servers', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once() - except SystemExit as e: - self.assertEqual(e.code, 0) - - @integration_test(scope="component") - def test_list_hosts_formatted_output(self): - """Test list hosts produces properly formatted output for environment-scoped listing.""" - # Setup mock environment manager with test data - mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - mock_env_manager.get_current_environment.return_value = "test-env" - mock_env_manager.environment_exists.return_value = True - mock_env_manager.get_environment_data.return_value = { - "packages": [ - { - "name": "weather-toolkit", - "configured_hosts": { - "claude-desktop": { - "config_path": "~/.claude/config.json", - "configured_at": "2025-09-25T10:00:00" - } - } - } - ] - } - - with patch('builtins.print') as mock_print: - result = handle_mcp_list_hosts(mock_env_manager, None, False) - - self.assertEqual(result, 0) - - # Verify environment-scoped output format - print_calls = [call[0][0] for call in mock_print.call_args_list] - output = ' '.join(print_calls) - self.assertIn("Configured hosts for environment 'test-env':", output) - self.assertIn("claude-desktop (1 packages)", output) - - @integration_test(scope="component") - def test_list_servers_formatted_output(self): - """Test list servers produces properly formatted table output.""" - # Mock packages with MCP servers - mock_packages = [ - {'name': 'weather-toolkit', 'version': '1.0.0'}, - {'name': 'file-manager', 'version': '2.1.0'} - ] - - self.mock_env_manager.list_packages.return_value = mock_packages - - # Mock get_package_mcp_server_config - def mock_get_config(env_manager, env_name, package_name): - return MCPServerConfig( - name=f"{package_name}-server", - command="python", - args=[f"{package_name}.py", "--port", "8080"], - env={} - ) - - with patch('hatch.cli_hatch.get_package_mcp_server_config', side_effect=mock_get_config): - with patch('builtins.print') as mock_print: - result = handle_mcp_list_servers(self.mock_env_manager, "test-env") - - self.assertEqual(result, 0) - - # Verify formatted table output - print_calls = [] - for call in mock_print.call_args_list: - if call[0]: # Check if args exist - print_calls.append(call[0][0]) - - self.assertTrue(any("MCP servers in environment 'test-env':" in call for call in print_calls)) - self.assertTrue(any("Server Name" in call for call in print_calls)) - self.assertTrue(any("weather-toolkit-server" in call for call in print_calls)) - self.assertTrue(any("file-manager-server" in call for call in print_calls)) - - -class TestMCPListHostsEnvironmentScoped(unittest.TestCase): - """Test suite for environment-scoped list hosts functionality.""" - - def setUp(self): - """Set up test fixtures.""" - self.mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - self.mock_env_manager.get_current_environment.return_value = "test-env" - self.mock_env_manager.environment_exists.return_value = True - # Configure the mock to have the get_environment_data method - self.mock_env_manager.get_environment_data = MagicMock() - - # Load test fixture data - fixture_path = Path(__file__).parent / "test_data" / "fixtures" / "environment_host_configs.json" - with open(fixture_path, 'r') as f: - self.test_data = json.load(f) - - @regression_test - def test_list_hosts_environment_scoped_basic(self): - """Test list hosts shows only hosts configured in specified environment. - - Validates: - - Reads from environment data (not system detection) - - Shows only hosts with configured packages in target environment - - Displays host count information correctly - - Uses environment manager for data source - """ - # Setup: Mock environment with 2 packages using different hosts - self.mock_env_manager.get_environment_data.return_value = self.test_data["multi_host_environment"] - - with patch('builtins.print') as mock_print: - # Action: Call handle_mcp_list_hosts with env_manager and env_name - result = handle_mcp_list_hosts(self.mock_env_manager, "test-env", False) - - # Assert: Success exit code - self.assertEqual(result, 0) - - # Assert: Environment manager methods called correctly - self.mock_env_manager.environment_exists.assert_called_with("test-env") - self.mock_env_manager.get_environment_data.assert_called_with("test-env") - - # Assert: Output contains both hosts with correct package counts - print_calls = [call[0][0] for call in mock_print.call_args_list] - output = ' '.join(print_calls) - - self.assertIn("Configured hosts for environment 'test-env':", output) - self.assertIn("claude-desktop (2 packages)", output) - self.assertIn("cursor (1 packages)", output) - - @regression_test - def test_list_hosts_empty_environment(self): - """Test list hosts with environment containing no packages. - - Validates: - - Handles empty environment gracefully - - Displays appropriate message for no configured hosts - - Returns success exit code (0) - - Does not attempt system detection - """ - # Setup: Mock environment with no packages - self.mock_env_manager.get_environment_data.return_value = self.test_data["empty_environment"] - - with patch('builtins.print') as mock_print: - # Action: Call handle_mcp_list_hosts - result = handle_mcp_list_hosts(self.mock_env_manager, "empty-env", False) - - # Assert: Success exit code - self.assertEqual(result, 0) - - # Assert: Appropriate message displayed - print_calls = [call[0][0] for call in mock_print.call_args_list] - output = ' '.join(print_calls) - self.assertIn("No configured hosts for environment 'empty-env'", output) - - @regression_test - def test_list_hosts_packages_no_host_tracking(self): - """Test list hosts with packages that have no configured_hosts data. - - Validates: - - Handles packages without configured_hosts gracefully - - Displays appropriate message for no host configurations - - Maintains backward compatibility with older environment data - """ - # Setup: Mock environment with packages lacking configured_hosts - self.mock_env_manager.get_environment_data.return_value = self.test_data["packages_no_host_tracking"] - - with patch('builtins.print') as mock_print: - # Action: Call handle_mcp_list_hosts - result = handle_mcp_list_hosts(self.mock_env_manager, "legacy-env", False) - - # Assert: Success exit code - self.assertEqual(result, 0) - - # Assert: Handles missing configured_hosts keys without error - print_calls = [call[0][0] for call in mock_print.call_args_list] - output = ' '.join(print_calls) - self.assertIn("No configured hosts for environment 'legacy-env'", output) - - -class TestMCPListHostsCLIIntegration(unittest.TestCase): - """Test suite for CLI argument processing.""" - - def setUp(self): - """Set up test fixtures.""" - self.mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - self.mock_env_manager.get_current_environment.return_value = "current-env" - self.mock_env_manager.environment_exists.return_value = True - # Configure the mock to have the get_environment_data method - self.mock_env_manager.get_environment_data = MagicMock(return_value={"packages": []}) - - @regression_test - def test_list_hosts_env_argument_parsing(self): - """Test --env argument processing for list hosts command. - - Validates: - - Accepts --env argument correctly - - Passes environment name to handler function - - Uses current environment when --env not specified - - Validates environment exists before processing - """ - # Test case 1: hatch mcp list hosts --env project-alpha - with patch('builtins.print'): - result = handle_mcp_list_hosts(self.mock_env_manager, "project-alpha", False) - self.assertEqual(result, 0) - self.mock_env_manager.environment_exists.assert_called_with("project-alpha") - self.mock_env_manager.get_environment_data.assert_called_with("project-alpha") - - # Reset mocks - self.mock_env_manager.reset_mock() - - # Test case 2: hatch mcp list hosts (uses current environment) - with patch('builtins.print'): - result = handle_mcp_list_hosts(self.mock_env_manager, None, False) - self.assertEqual(result, 0) - self.mock_env_manager.get_current_environment.assert_called_once() - self.mock_env_manager.environment_exists.assert_called_with("current-env") - - @regression_test - def test_list_hosts_detailed_flag_parsing(self): - """Test --detailed flag processing for list hosts command. - - Validates: - - Accepts --detailed flag correctly - - Passes detailed flag to handler function - - Default behavior when flag not specified - """ - # Load test data with detailed information - fixture_path = Path(__file__).parent / "test_data" / "fixtures" / "environment_host_configs.json" - with open(fixture_path, 'r') as f: - test_data = json.load(f) - - self.mock_env_manager.get_environment_data.return_value = test_data["single_host_environment"] - - with patch('builtins.print') as mock_print: - # Test: hatch mcp list hosts --detailed - result = handle_mcp_list_hosts(self.mock_env_manager, "test-env", True) - - # Assert: detailed=True passed to handler - self.assertEqual(result, 0) - - # Assert: Detailed output includes config paths and timestamps - print_calls = [call[0][0] for call in mock_print.call_args_list] - output = ' '.join(print_calls) - self.assertIn("Config path:", output) - self.assertIn("Configured at:", output) - - -class TestMCPListHostsEnvironmentManagerIntegration(unittest.TestCase): - """Test suite for environment manager integration.""" - - def setUp(self): - """Set up test fixtures.""" - self.mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - # Configure the mock to have the get_environment_data method - self.mock_env_manager.get_environment_data = MagicMock() - - @integration_test(scope="component") - def test_list_hosts_reads_environment_data(self): - """Test list hosts reads actual environment data via environment manager. - - Validates: - - Calls environment manager methods correctly - - Processes configured_hosts data from packages - - Aggregates hosts across multiple packages - - Handles environment resolution (current vs specified) - """ - # Setup: Real environment manager with test data - fixture_path = Path(__file__).parent / "test_data" / "fixtures" / "environment_host_configs.json" - with open(fixture_path, 'r') as f: - test_data = json.load(f) - - self.mock_env_manager.get_current_environment.return_value = "test-env" - self.mock_env_manager.environment_exists.return_value = True - self.mock_env_manager.get_environment_data.return_value = test_data["multi_host_environment"] - - with patch('builtins.print'): - # Action: Call list hosts functionality - result = handle_mcp_list_hosts(self.mock_env_manager, None, False) - - # Assert: Correct environment manager method calls - self.mock_env_manager.get_current_environment.assert_called_once() - self.mock_env_manager.environment_exists.assert_called_with("test-env") - self.mock_env_manager.get_environment_data.assert_called_with("test-env") - - # Assert: Success result - self.assertEqual(result, 0) - - @integration_test(scope="component") - def test_list_hosts_environment_validation(self): - """Test list hosts validates environment existence. - - Validates: - - Checks environment exists before processing - - Returns appropriate error for non-existent environment - - Provides helpful error message with available environments - """ - # Setup: Environment manager with known environments - self.mock_env_manager.environment_exists.return_value = False - self.mock_env_manager.list_environments.return_value = ["env1", "env2", "env3"] - - with patch('builtins.print') as mock_print: - # Action: Call list hosts with non-existent environment - result = handle_mcp_list_hosts(self.mock_env_manager, "non-existent", False) - - # Assert: Error message includes available environments - print_calls = [call[0][0] for call in mock_print.call_args_list] - output = ' '.join(print_calls) - self.assertIn("Environment 'non-existent' does not exist", output) - self.assertIn("Available environments: env1, env2, env3", output) - - # Assert: Non-zero exit code - self.assertEqual(result, 1) - - -class TestMCPDiscoverHostsUnchanged(unittest.TestCase): - """Test suite for discover hosts unchanged behavior.""" - - def setUp(self): - """Set up test fixtures.""" - self.mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - - @regression_test - def test_discover_hosts_system_detection_unchanged(self): - """Test discover hosts continues to use system detection. - - Validates: - - Uses host strategy detection (not environment data) - - Shows availability status for detected hosts - - Behavior unchanged from previous implementation - - No environment dependency - """ - # Setup: Mock host strategies with available hosts - with patch('hatch.mcp_host_config.strategies'): # Import strategies - with patch('hatch.cli_hatch.MCPHostRegistry') as mock_registry: - mock_registry.detect_available_hosts.return_value = [ - MCPHostType.CLAUDE_DESKTOP, - MCPHostType.CURSOR - ] - - # Mock strategy for each host type - mock_strategy = MagicMock() - mock_strategy.get_config_path.return_value = Path("~/.claude/config.json") - mock_registry.get_strategy.return_value = mock_strategy - - with patch('builtins.print') as mock_print: - # Action: Call handle_mcp_discover_hosts - result = handle_mcp_discover_hosts() - - # Assert: Host strategy detection called - mock_registry.detect_available_hosts.assert_called_once() - - # Assert: No environment manager calls (discover hosts is environment-independent) - # Note: discover hosts doesn't use environment manager at all - - # Assert: Availability-focused output format - print_calls = [call[0][0] for call in mock_print.call_args_list] - output = ' '.join(print_calls) - self.assertIn("Available MCP host platforms:", output) - self.assertIn("Available", output) - - # Assert: Success result - self.assertEqual(result, 0) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_cli_host_config_integration.py b/tests/test_mcp_cli_host_config_integration.py deleted file mode 100644 index 468c074..0000000 --- a/tests/test_mcp_cli_host_config_integration.py +++ /dev/null @@ -1,823 +0,0 @@ -""" -Test suite for MCP CLI host configuration integration. - -This module tests the integration of the Pydantic model hierarchy (Phase 3B) -and user feedback reporting system (Phase 3C) into Hatch's CLI commands. - -Tests focus on CLI-specific integration logic while leveraging existing test -infrastructure from Phases 3A-3C. -""" - -import unittest -import sys -from pathlib import Path -from unittest.mock import patch, MagicMock, call, ANY - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import regression_test, integration_test -except ImportError: - # Fallback decorators if wobble is not available - def regression_test(func): - return func - - def integration_test(scope="component"): - def decorator(func): - return func - return decorator - -from hatch.cli_hatch import ( - handle_mcp_configure, - parse_env_vars, - parse_header, - parse_host_list, -) -from hatch.mcp_host_config.models import ( - MCPServerConfig, - MCPServerConfigOmni, - HOST_MODEL_REGISTRY, - MCPHostType, - MCPServerConfigGemini, - MCPServerConfigVSCode, - MCPServerConfigCursor, - MCPServerConfigClaude, -) -from hatch.mcp_host_config.reporting import ( - generate_conversion_report, - display_report, - FieldOperation, - ConversionReport, -) - - -class TestCLIArgumentParsingToOmniCreation(unittest.TestCase): - """Test suite for CLI argument parsing to MCPServerConfigOmni creation.""" - - @regression_test - def test_configure_creates_omni_model_basic(self): - """Test that configure command creates MCPServerConfigOmni from CLI arguments.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Call handle_mcp_configure with basic arguments - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify the function executed without errors - self.assertEqual(result, 0) - - @regression_test - def test_configure_creates_omni_with_env_vars(self): - """Test that environment variables are parsed correctly into Omni model.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Call with environment variables - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['server.py'], - env=['API_KEY=secret', 'DEBUG=true'], - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify the function executed without errors - self.assertEqual(result, 0) - - @regression_test - def test_configure_creates_omni_with_headers(self): - """Test that headers are parsed correctly into Omni model.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - result = handle_mcp_configure( - host='gemini', # Use gemini which supports remote servers - server_name='test-server', - command=None, - args=None, - env=None, - url='https://api.example.com', - header=['Authorization=Bearer token', 'Content-Type=application/json'], - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify the function executed without errors (bug fixed in Phase 4) - self.assertEqual(result, 0) - - @regression_test - def test_configure_creates_omni_remote_server(self): - """Test that remote server arguments create correct Omni model.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - result = handle_mcp_configure( - host='gemini', # Use gemini which supports remote servers - server_name='remote-server', - command=None, - args=None, - env=None, - url='https://api.example.com', - header=['Auth=token'], - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify the function executed without errors (bug fixed in Phase 4) - self.assertEqual(result, 0) - - @regression_test - def test_configure_omni_with_all_universal_fields(self): - """Test that all universal fields are supported in Omni creation.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Call with all universal fields - result = handle_mcp_configure( - host='claude-desktop', - server_name='full-server', - command='python', - args=['server.py', '--port', '8080'], - env=['API_KEY=secret', 'DEBUG=true', 'LOG_LEVEL=info'], - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify the function executed without errors - self.assertEqual(result, 0) - - @regression_test - def test_configure_omni_with_optional_fields_none(self): - """Test that optional fields are handled correctly (None values).""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Call with only required fields - result = handle_mcp_configure( - host='claude-desktop', - server_name='minimal-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify the function executed without errors - self.assertEqual(result, 0) - - -class TestModelIntegration(unittest.TestCase): - """Test suite for model integration in CLI handlers.""" - - @regression_test - def test_configure_uses_host_model_registry(self): - """Test that configure command uses HOST_MODEL_REGISTRY for host selection.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Test with Gemini host - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify the function executed without errors - self.assertEqual(result, 0) - - @regression_test - def test_configure_calls_from_omni_conversion(self): - """Test that from_omni() is called to convert Omni to host-specific model.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Call configure command - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify the function executed without errors - self.assertEqual(result, 0) - - @integration_test(scope="component") - def test_configure_passes_host_specific_model_to_manager(self): - """Test that host-specific model is passed to MCPHostConfigurationManager.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.configure_server.return_value = MagicMock(success=True, backup_path=None) - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - # Call configure command - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify configure_server was called - self.assertEqual(result, 0) - mock_manager.configure_server.assert_called_once() - - # Verify the server_config argument is a host-specific model instance - # (MCPServerConfigClaude for claude-desktop host) - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertIsInstance(server_config, MCPServerConfigClaude) - - -class TestReportingIntegration(unittest.TestCase): - """Test suite for reporting integration in CLI commands.""" - - @regression_test - def test_configure_dry_run_displays_report_only(self): - """Test that dry-run mode displays report without configuration.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - # Call with dry-run - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - no_backup=True, - dry_run=True, - auto_approve=False - ) - - # Verify the function executed without errors - self.assertEqual(result, 0) - - # Verify MCPHostConfigurationManager.create_server was NOT called (dry-run doesn't persist) - # Note: get_server_config is called to check if server exists, but create_server is not called - mock_manager.return_value.create_server.assert_not_called() - - -class TestHostSpecificArguments(unittest.TestCase): - """Test suite for host-specific CLI arguments (Phase 3 - Mandatory).""" - - @regression_test - def test_configure_accepts_all_universal_fields(self): - """Test that all universal fields are accepted by CLI.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Call with all universal fields - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['server.py', '--port', '8080'], - env=['API_KEY=secret', 'DEBUG=true'], - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify success - self.assertEqual(result, 0) - - @regression_test - def test_configure_multiple_env_vars(self): - """Test that multiple environment variables are handled correctly.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Call with multiple env vars - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command='python', - args=['server.py'], - env=['VAR1=value1', 'VAR2=value2', 'VAR3=value3'], - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify success - self.assertEqual(result, 0) - - @regression_test - def test_configure_different_hosts(self): - """Test that different host types are handled correctly.""" - hosts_to_test = ['claude-desktop', 'cursor', 'vscode', 'gemini'] - - for host in hosts_to_test: - with self.subTest(host=host): - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - result = handle_mcp_configure( - host=host, - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify success for each host - self.assertEqual(result, 0) - - -class TestErrorHandling(unittest.TestCase): - """Test suite for error handling in CLI commands.""" - - @regression_test - def test_configure_invalid_host_type_error(self): - """Test that clear error is shown for invalid host type.""" - # Call with invalid host - result = handle_mcp_configure( - host='invalid-host', - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify error return code - self.assertEqual(result, 1) - - @regression_test - def test_configure_invalid_field_value_error(self): - """Test that clear error is shown for invalid field values.""" - # Test with invalid URL format - this will be caught by Pydantic validation - # when creating MCPServerConfig - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command=None, - args=None, # Must be None for remote server - env=None, - url='not-a-url', # Invalid URL format - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify error return code (validation error caught in exception handler) - self.assertEqual(result, 1) - - @regression_test - def test_configure_pydantic_validation_error_handling(self): - """Test that Pydantic ValidationErrors are caught and handled.""" - # Test with conflicting arguments (command with headers) - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=['Auth=token'], # Headers not allowed with command - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify error return code (caught by validation in handle_mcp_configure) - self.assertEqual(result, 1) - - @regression_test - def test_configure_missing_command_url_error(self): - """Test error handling when neither command nor URL provided.""" - # This test verifies the argparse validation (required=True for mutually exclusive group) - # In actual CLI usage, argparse would catch this before handle_mcp_configure is called - # For unit testing, we test that the function handles None values appropriately - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command=None, - args=None, - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify error return code (validation error) - self.assertEqual(result, 1) - - -class TestBackwardCompatibility(unittest.TestCase): - """Test suite for backward compatibility.""" - - @regression_test - def test_existing_configure_command_still_works(self): - """Test that existing configure command usage still works.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.configure_server.return_value = MagicMock(success=True, backup_path=None) - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - # Call with existing command pattern - result = handle_mcp_configure( - host='claude-desktop', - server_name='my-server', - command='python', - args=['-m', 'my_package.server'], - env=['API_KEY=secret'], - url=None, - header=None, - no_backup=False, - dry_run=False, - auto_approve=False - ) - - # Verify success - self.assertEqual(result, 0) - mock_manager.configure_server.assert_called_once() - - -class TestParseUtilities(unittest.TestCase): - """Test suite for CLI parsing utilities.""" - - @regression_test - def test_parse_env_vars_basic(self): - """Test parsing environment variables from KEY=VALUE format.""" - env_list = ['API_KEY=secret', 'DEBUG=true'] - result = parse_env_vars(env_list) - - expected = {'API_KEY': 'secret', 'DEBUG': 'true'} - self.assertEqual(result, expected) - - @regression_test - def test_parse_env_vars_empty(self): - """Test parsing empty environment variables list.""" - result = parse_env_vars(None) - self.assertEqual(result, {}) - - result = parse_env_vars([]) - self.assertEqual(result, {}) - - @regression_test - def test_parse_header_basic(self): - """Test parsing headers from KEY=VALUE format.""" - headers_list = ['Authorization=Bearer token', 'Content-Type=application/json'] - result = parse_header(headers_list) - - expected = {'Authorization': 'Bearer token', 'Content-Type': 'application/json'} - self.assertEqual(result, expected) - - @regression_test - def test_parse_header_empty(self): - """Test parsing empty headers list.""" - result = parse_header(None) - self.assertEqual(result, {}) - - result = parse_header([]) - self.assertEqual(result, {}) - - -class TestCLIIntegrationReadiness(unittest.TestCase): - """Test suite to verify readiness for Phase 4 CLI integration implementation.""" - - @regression_test - def test_host_model_registry_available(self): - """Test that HOST_MODEL_REGISTRY is available for CLI integration.""" - from hatch.mcp_host_config.models import HOST_MODEL_REGISTRY, MCPHostType - - # Verify registry contains all expected hosts - expected_hosts = [ - MCPHostType.GEMINI, - MCPHostType.CLAUDE_DESKTOP, - MCPHostType.CLAUDE_CODE, - MCPHostType.VSCODE, - MCPHostType.CURSOR, - MCPHostType.LMSTUDIO, - ] - - for host in expected_hosts: - self.assertIn(host, HOST_MODEL_REGISTRY) - - @regression_test - def test_omni_model_available(self): - """Test that MCPServerConfigOmni is available for CLI integration.""" - from hatch.mcp_host_config.models import MCPServerConfigOmni - - # Create a basic Omni model - omni = MCPServerConfigOmni( - name='test-server', - command='python', - args=['server.py'], - env={'API_KEY': 'secret'}, - ) - - # Verify model was created successfully - self.assertEqual(omni.name, 'test-server') - self.assertEqual(omni.command, 'python') - self.assertEqual(omni.args, ['server.py']) - self.assertEqual(omni.env, {'API_KEY': 'secret'}) - - @regression_test - def test_from_omni_conversion_available(self): - """Test that from_omni() conversion is available for all host models.""" - from hatch.mcp_host_config.models import ( - MCPServerConfigOmni, - MCPServerConfigGemini, - MCPServerConfigClaude, - MCPServerConfigVSCode, - MCPServerConfigCursor, - ) - - # Create Omni model - omni = MCPServerConfigOmni( - name='test-server', - command='python', - args=['server.py'], - ) - - # Test conversion to each host-specific model - gemini = MCPServerConfigGemini.from_omni(omni) - self.assertEqual(gemini.name, 'test-server') - - claude = MCPServerConfigClaude.from_omni(omni) - self.assertEqual(claude.name, 'test-server') - - vscode = MCPServerConfigVSCode.from_omni(omni) - self.assertEqual(vscode.name, 'test-server') - - cursor = MCPServerConfigCursor.from_omni(omni) - self.assertEqual(cursor.name, 'test-server') - - @regression_test - def test_reporting_functions_available(self): - """Test that reporting functions are available for CLI integration.""" - from hatch.mcp_host_config.reporting import ( - generate_conversion_report, - display_report, - ) - from hatch.mcp_host_config.models import MCPServerConfigOmni, MCPHostType - - # Create Omni model - omni = MCPServerConfigOmni( - name='test-server', - command='python', - args=['server.py'], - ) - - # Generate report - report = generate_conversion_report( - operation='create', - server_name='test-server', - target_host=MCPHostType.CLAUDE_DESKTOP, - omni=omni, - dry_run=True - ) - - # Verify report was created - self.assertIsNotNone(report) - self.assertEqual(report.operation, 'create') - - @regression_test - def test_claude_desktop_rejects_url_configuration(self): - """Test Claude Desktop rejects remote server (--url) configurations (Issue 2).""" - with patch('hatch.cli_hatch.print') as mock_print: - result = handle_mcp_configure( - host='claude-desktop', - server_name='remote-server', - command=None, - args=None, - env=None, - url='http://localhost:8080', # Should be rejected - header=None, - no_backup=True, - dry_run=False, - auto_approve=True - ) - - # Validate: Should return error code 1 - self.assertEqual(result, 1) - - # Validate: Error message displayed - error_calls = [call for call in mock_print.call_args_list - if 'Error' in str(call) or 'error' in str(call)] - self.assertTrue(len(error_calls) > 0, "Expected error message to be printed") - - @regression_test - def test_claude_code_rejects_url_configuration(self): - """Test Claude Code (same family) also rejects remote servers (Issue 2).""" - with patch('hatch.cli_hatch.print') as mock_print: - result = handle_mcp_configure( - host='claude-code', - server_name='remote-server', - command=None, - args=None, - env=None, - url='http://localhost:8080', - header=None, - no_backup=True, - dry_run=False, - auto_approve=True - ) - - # Validate: Should return error code 1 - self.assertEqual(result, 1) - - # Validate: Error message displayed - error_calls = [call for call in mock_print.call_args_list - if 'Error' in str(call) or 'error' in str(call)] - self.assertTrue(len(error_calls) > 0, "Expected error message to be printed") - - @regression_test - def test_args_quoted_string_splitting(self): - """Test that quoted strings in --args are properly split (Issue 4).""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Simulate user providing: --args "-r --name aName" - # This arrives as a single string element in the args list - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['-r --name aName'], # Single string with quoted content - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify: Should succeed (return 0) - self.assertEqual(result, 0) - - # Verify: MCPServerConfigOmni was created with split args - call_args = mock_manager.return_value.create_server.call_args - if call_args: - omni_config = call_args[1]['omni'] - # Args should be split into 3 elements: ['-r', '--name', 'aName'] - self.assertEqual(omni_config.args, ['-r', '--name', 'aName']) - - @regression_test - def test_args_multiple_quoted_strings(self): - """Test multiple quoted strings in --args are all split correctly (Issue 4).""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Simulate: --args "-r" "--name aName" - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['-r', '--name aName'], # Two separate args - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify: Should succeed - self.assertEqual(result, 0) - - # Verify: All args are properly split - call_args = mock_manager.return_value.create_server.call_args - if call_args: - omni_config = call_args[1]['omni'] - # Should be split into: ['-r', '--name', 'aName'] - self.assertEqual(omni_config.args, ['-r', '--name', 'aName']) - - @regression_test - def test_args_empty_string_handling(self): - """Test that empty strings in --args are filtered out (Issue 4).""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - # Simulate: --args "" "server.py" - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['', 'server.py'], # Empty string should be filtered - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify: Should succeed - self.assertEqual(result, 0) - - # Verify: Empty strings are filtered out - call_args = mock_manager.return_value.create_server.call_args - if call_args: - omni_config = call_args[1]['omni'] - # Should only contain 'server.py' - self.assertEqual(omni_config.args, ['server.py']) - - @regression_test - def test_args_invalid_quote_handling(self): - """Test that invalid quotes in --args are handled gracefully (Issue 4).""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager: - with patch('hatch.cli_hatch.request_confirmation', return_value=False): - with patch('hatch.cli_hatch.print') as mock_print: - # Simulate: --args 'unclosed "quote' - result = handle_mcp_configure( - host='claude-desktop', - server_name='test-server', - command='python', - args=['unclosed "quote'], # Invalid quote - env=None, - url=None, - header=None, - no_backup=True, - dry_run=False, - auto_approve=False - ) - - # Verify: Should succeed (graceful fallback) - self.assertEqual(result, 0) - - # Verify: Warning was printed - warning_calls = [call for call in mock_print.call_args_list - if 'Warning' in str(call)] - self.assertTrue(len(warning_calls) > 0, "Expected warning for invalid quote") - - # Verify: Original arg is used as fallback - call_args = mock_manager.return_value.create_server.call_args - if call_args: - omni_config = call_args[1]['omni'] - self.assertIn('unclosed "quote', omni_config.args) - - @regression_test - def test_cli_handler_signature_compatible(self): - """Test that handle_mcp_configure signature is compatible with integration.""" - import inspect - from hatch.cli_hatch import handle_mcp_configure - - # Get function signature - sig = inspect.signature(handle_mcp_configure) - - # Verify expected parameters exist - expected_params = [ - 'host', 'server_name', 'command', 'args', - 'env', 'url', 'header', 'no_backup', 'dry_run', 'auto_approve' - ] - - for param in expected_params: - self.assertIn(param, sig.parameters) - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/test_mcp_cli_package_management.py b/tests/test_mcp_cli_package_management.py deleted file mode 100644 index 75fb8e1..0000000 --- a/tests/test_mcp_cli_package_management.py +++ /dev/null @@ -1,360 +0,0 @@ -""" -Test suite for MCP CLI package management enhancements. - -This module tests the enhanced package management commands with MCP host -configuration integration following CrackingShells testing standards. -""" - -import sys -import unittest -from pathlib import Path -from unittest.mock import MagicMock, mock_open, patch - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import integration_test, regression_test -except ImportError: - # Fallback decorators if wobble is not available - def regression_test(func): - return func - - def integration_test(scope="component"): - def decorator(func): - return func - - return decorator - - -from hatch.cli_hatch import ( - get_package_mcp_server_config, - parse_host_list, - request_confirmation, -) -from hatch.mcp_host_config import MCPHostType, MCPServerConfig - - -class TestMCPCLIPackageManagement(unittest.TestCase): - """Test suite for MCP CLI package management enhancements.""" - - @regression_test - def test_parse_host_list_comma_separated(self): - """Test parsing comma-separated host list.""" - hosts = parse_host_list("claude-desktop,cursor,vscode") - expected = [MCPHostType.CLAUDE_DESKTOP, MCPHostType.CURSOR, MCPHostType.VSCODE] - self.assertEqual(hosts, expected) - - @regression_test - def test_parse_host_list_single_host(self): - """Test parsing single host.""" - hosts = parse_host_list("claude-desktop") - expected = [MCPHostType.CLAUDE_DESKTOP] - self.assertEqual(hosts, expected) - - @regression_test - def test_parse_host_list_empty(self): - """Test parsing empty host list.""" - hosts = parse_host_list("") - self.assertEqual(hosts, []) - - @regression_test - def test_parse_host_list_none(self): - """Test parsing None host list.""" - hosts = parse_host_list(None) - self.assertEqual(hosts, []) - - @regression_test - def test_parse_host_list_all(self): - """Test parsing 'all' host list.""" - with patch( - "hatch.cli_hatch.MCPHostRegistry.detect_available_hosts" - ) as mock_detect: - mock_detect.return_value = [MCPHostType.CLAUDE_DESKTOP, MCPHostType.CURSOR] - hosts = parse_host_list("all") - expected = [MCPHostType.CLAUDE_DESKTOP, MCPHostType.CURSOR] - self.assertEqual(hosts, expected) - mock_detect.assert_called_once() - - @regression_test - def test_parse_host_list_invalid_host(self): - """Test parsing invalid host raises ValueError.""" - with self.assertRaises(ValueError) as context: - parse_host_list("invalid-host") - - self.assertIn("Unknown host 'invalid-host'", str(context.exception)) - self.assertIn("Available:", str(context.exception)) - - @regression_test - def test_parse_host_list_mixed_valid_invalid(self): - """Test parsing mixed valid and invalid hosts.""" - with self.assertRaises(ValueError) as context: - parse_host_list("claude-desktop,invalid-host,cursor") - - self.assertIn("Unknown host 'invalid-host'", str(context.exception)) - - @regression_test - def test_parse_host_list_whitespace_handling(self): - """Test parsing host list with whitespace.""" - hosts = parse_host_list(" claude-desktop , cursor , vscode ") - expected = [MCPHostType.CLAUDE_DESKTOP, MCPHostType.CURSOR, MCPHostType.VSCODE] - self.assertEqual(hosts, expected) - - @regression_test - def test_request_confirmation_auto_approve(self): - """Test confirmation with auto-approve flag.""" - result = request_confirmation("Test message?", auto_approve=True) - self.assertTrue(result) - - @regression_test - def test_request_confirmation_user_yes(self): - """Test confirmation with user saying yes.""" - with patch("builtins.input", return_value="y"): - result = request_confirmation("Test message?", auto_approve=False) - self.assertTrue(result) - - @regression_test - def test_request_confirmation_user_yes_full(self): - """Test confirmation with user saying 'yes'.""" - with patch("builtins.input", return_value="yes"): - result = request_confirmation("Test message?", auto_approve=False) - self.assertTrue(result) - - @regression_test - def test_request_confirmation_user_no(self): - """Test confirmation with user saying no.""" - with patch.dict("os.environ", {"HATCH_AUTO_APPROVE": ""}, clear=False): - with patch("builtins.input", return_value="n"): - result = request_confirmation("Test message?", auto_approve=False) - self.assertFalse(result) - - @regression_test - def test_request_confirmation_user_no_full(self): - """Test confirmation with user saying 'no'.""" - with patch.dict("os.environ", {"HATCH_AUTO_APPROVE": ""}, clear=False): - with patch("builtins.input", return_value="no"): - result = request_confirmation("Test message?", auto_approve=False) - self.assertFalse(result) - - @regression_test - def test_request_confirmation_user_empty(self): - """Test confirmation with user pressing enter (default no).""" - with patch.dict("os.environ", {"HATCH_AUTO_APPROVE": ""}, clear=False): - with patch("builtins.input", return_value=""): - result = request_confirmation("Test message?", auto_approve=False) - self.assertFalse(result) - - @integration_test(scope="component") - def test_package_add_argument_parsing(self): - """Test package add command argument parsing with MCP flags.""" - import argparse - - from hatch.cli_hatch import main - - # Mock argparse to capture parsed arguments - with patch("argparse.ArgumentParser.parse_args") as mock_parse: - mock_args = MagicMock() - mock_args.command = "package" - mock_args.pkg_command = "add" - mock_args.package_path_or_name = "test-package" - mock_args.host = "claude-desktop,cursor" - mock_args.env = None - mock_args.version = None - mock_args.force_download = False - mock_args.refresh_registry = False - mock_args.auto_approve = False - mock_parse.return_value = mock_args - - # Mock environment manager to avoid actual operations - with patch("hatch.cli_hatch.HatchEnvironmentManager") as mock_env_manager: - mock_env_manager.return_value.add_package_to_environment.return_value = True - mock_env_manager.return_value.get_current_environment.return_value = ( - "default" - ) - - # Mock MCP manager - with patch("hatch.cli_hatch.MCPHostConfigurationManager"): - with patch("builtins.print") as mock_print: - result = main() - - # Should succeed - self.assertEqual(result, 0) - - # Should print success message - mock_print.assert_any_call( - "Successfully added package: test-package" - ) - - @integration_test(scope="component") - def test_package_sync_argument_parsing(self): - """Test package sync command argument parsing.""" - import argparse - - from hatch.cli_hatch import main - - # Mock argparse to capture parsed arguments - with patch("argparse.ArgumentParser.parse_args") as mock_parse: - mock_args = MagicMock() - mock_args.command = "package" - mock_args.pkg_command = "sync" - mock_args.package_name = "test-package" - mock_args.host = "claude-desktop,cursor" - mock_args.env = None - mock_args.dry_run = True # Use dry run to avoid actual configuration - mock_args.auto_approve = False - mock_args.no_backup = False - mock_parse.return_value = mock_args - - # Mock the get_package_mcp_server_config function - with patch( - "hatch.cli_hatch.get_package_mcp_server_config" - ) as mock_get_config: - mock_server_config = MagicMock() - mock_server_config.name = "test-package" - mock_server_config.args = ["/path/to/server.py"] - mock_get_config.return_value = mock_server_config - - # Mock environment manager - with patch( - "hatch.cli_hatch.HatchEnvironmentManager" - ) as mock_env_manager: - mock_env_manager.return_value.get_current_environment.return_value = "default" - - # Mock MCP manager - with patch("hatch.cli_hatch.MCPHostConfigurationManager"): - with patch("builtins.print") as mock_print: - result = main() - - # Should succeed - self.assertEqual(result, 0) - - # Should print dry run message (new format includes dependency info) - mock_print.assert_any_call( - "[DRY RUN] Would synchronize MCP servers for 1 package(s) to hosts: ['claude-desktop', 'cursor']" - ) - - @integration_test(scope="component") - def test_package_sync_package_not_found(self): - """Test package sync when package doesn't exist.""" - import argparse - - from hatch.cli_hatch import main - - # Mock argparse to capture parsed arguments - with patch("argparse.ArgumentParser.parse_args") as mock_parse: - mock_args = MagicMock() - mock_args.command = "package" - mock_args.pkg_command = "sync" - mock_args.package_name = "nonexistent-package" - mock_args.host = "claude-desktop" - mock_args.env = None - mock_args.dry_run = False - mock_args.auto_approve = False - mock_args.no_backup = False - mock_parse.return_value = mock_args - - # Mock the get_package_mcp_server_config function to raise ValueError - with patch( - "hatch.cli_hatch.get_package_mcp_server_config" - ) as mock_get_config: - mock_get_config.side_effect = ValueError( - "Package 'nonexistent-package' not found in environment 'default'" - ) - - # Mock environment manager - with patch( - "hatch.cli_hatch.HatchEnvironmentManager" - ) as mock_env_manager: - mock_env_manager.return_value.get_current_environment.return_value = "default" - - with patch("builtins.print") as mock_print: - result = main() - - # Should fail - self.assertEqual(result, 1) - - # Should print error message (new format) - mock_print.assert_any_call( - "Error: No MCP server configurations found for package 'nonexistent-package' or its dependencies" - ) - - @regression_test - def test_get_package_mcp_server_config_success(self): - """Test successful MCP server config retrieval.""" - # Mock environment manager - mock_env_manager = MagicMock() - mock_env_manager.list_packages.return_value = [ - { - "name": "test-package", - "version": "1.0.0", - "source": {"path": "/path/to/package"}, - } - ] - # Mock the Python executable method to return a proper string - mock_env_manager.get_current_python_executable.return_value = "/path/to/python" - - # Mock file system and metadata - with patch("pathlib.Path.exists", return_value=True): - with patch( - "builtins.open", - mock_open( - read_data='{"package_schema_version": "1.2.1", "name": "test-package"}' - ), - ): - with patch( - "hatch_validator.package.package_service.PackageService" - ) as mock_service_class: - mock_service = MagicMock() - mock_service.get_mcp_entry_point.return_value = "mcp_server.py" - mock_service_class.return_value = mock_service - - config = get_package_mcp_server_config( - mock_env_manager, "test-env", "test-package" - ) - - self.assertIsInstance(config, MCPServerConfig) - self.assertEqual(config.name, "test-package") - self.assertEqual( - config.command, "/path/to/python" - ) # Now uses environment-specific Python - self.assertTrue(config.args[0].endswith("mcp_server.py")) - - @regression_test - def test_get_package_mcp_server_config_package_not_found(self): - """Test MCP server config retrieval when package not found.""" - # Mock environment manager with empty package list - mock_env_manager = MagicMock() - mock_env_manager.list_packages.return_value = [] - - with self.assertRaises(ValueError) as context: - get_package_mcp_server_config( - mock_env_manager, "test-env", "nonexistent-package" - ) - - self.assertIn("Package 'nonexistent-package' not found", str(context.exception)) - - @regression_test - def test_get_package_mcp_server_config_no_metadata(self): - """Test MCP server config retrieval when package has no metadata.""" - # Mock environment manager - mock_env_manager = MagicMock() - mock_env_manager.list_packages.return_value = [ - { - "name": "test-package", - "version": "1.0.0", - "source": {"path": "/path/to/package"}, - } - ] - - # Mock file system - metadata file doesn't exist - with patch("pathlib.Path.exists", return_value=False): - with self.assertRaises(ValueError) as context: - get_package_mcp_server_config( - mock_env_manager, "test-env", "test-package" - ) - - self.assertIn("not a Hatch package", str(context.exception)) - - -if __name__ == "__main__": - unittest.main() diff --git a/tests/test_mcp_cli_partial_updates.py b/tests/test_mcp_cli_partial_updates.py deleted file mode 100644 index d20e9a5..0000000 --- a/tests/test_mcp_cli_partial_updates.py +++ /dev/null @@ -1,859 +0,0 @@ -""" -Test suite for MCP CLI partial configuration update functionality. - -This module tests the partial configuration update feature that allows users to modify -specific fields without re-specifying entire server configurations. - -Tests cover: -- Server existence detection (get_server_config method) -- Partial update validation (create vs. update logic) -- Field preservation (merge logic) -- Command/URL switching behavior -- End-to-end integration workflows -- Backward compatibility -""" - -import unittest -from unittest.mock import patch, MagicMock, call -import sys -from pathlib import Path - -# Add the parent directory to the path to import hatch modules -sys.path.insert(0, str(Path(__file__).parent.parent)) - -from hatch.mcp_host_config.host_management import MCPHostConfigurationManager -from hatch.mcp_host_config.models import MCPHostType, MCPServerConfig, MCPServerConfigOmni -from hatch.cli_hatch import handle_mcp_configure -from wobble import regression_test, integration_test - - -class TestServerExistenceDetection(unittest.TestCase): - """Test suite for server existence detection (Category A).""" - - @regression_test - def test_get_server_config_exists(self): - """Test A1: get_server_config returns existing server configuration.""" - # Setup: Create a test server configuration - manager = MCPHostConfigurationManager() - - # Mock the strategy to return a configuration with our test server - mock_strategy = MagicMock() - mock_config = MagicMock() - test_server = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"], - env={"API_KEY": "test_key"} - ) - mock_config.servers = {"test-server": test_server} - mock_strategy.read_configuration.return_value = mock_config - - with patch.object(manager.host_registry, 'get_strategy', return_value=mock_strategy): - # Execute - result = manager.get_server_config("claude-desktop", "test-server") - - # Validate - self.assertIsNotNone(result) - self.assertEqual(result.name, "test-server") - self.assertEqual(result.command, "python") - - @regression_test - def test_get_server_config_not_exists(self): - """Test A2: get_server_config returns None for non-existent server.""" - # Setup: Empty registry - manager = MCPHostConfigurationManager() - - mock_strategy = MagicMock() - mock_config = MagicMock() - mock_config.servers = {} # No servers - mock_strategy.read_configuration.return_value = mock_config - - with patch.object(manager.host_registry, 'get_strategy', return_value=mock_strategy): - # Execute - result = manager.get_server_config("claude-desktop", "non-existent-server") - - # Validate - self.assertIsNone(result) - - @regression_test - def test_get_server_config_invalid_host(self): - """Test A3: get_server_config handles invalid host gracefully.""" - # Setup - manager = MCPHostConfigurationManager() - - # Execute: Invalid host should be handled gracefully - result = manager.get_server_config("invalid-host", "test-server") - - # Validate: Should return None, not raise exception - self.assertIsNone(result) - - -class TestPartialUpdateValidation(unittest.TestCase): - """Test suite for partial update validation (Category B).""" - - @regression_test - def test_configure_update_single_field_timeout(self): - """Test B1: Update single field (timeout) preserves other fields.""" - # Setup: Existing server with timeout=30 - existing_server = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"], - env={"API_KEY": "test_key"}, - timeout=30 - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Update only timeout (use Gemini which supports timeout) - result = handle_mcp_configure( - host="gemini", - server_name="test-server", - command=None, - args=None, - env=None, - url=None, - header=None, - timeout=60, # Only timeout provided - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - - # Validate: configure_server was called with merged config - mock_manager.configure_server.assert_called_once() - call_args = mock_manager.configure_server.call_args - host_config = call_args[1]['server_config'] - - # Timeout should be updated (Gemini supports timeout) - self.assertEqual(host_config.timeout, 60) - # Other fields should be preserved - self.assertEqual(host_config.command, "python") - self.assertEqual(host_config.args, ["server.py"]) - - @regression_test - def test_configure_update_env_vars_only(self): - """Test B2: Update environment variables only preserves other fields.""" - # Setup: Existing server with env vars - existing_server = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"], - env={"API_KEY": "old_key"} - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Update only env vars - result = handle_mcp_configure( - host="claude-desktop", - server_name="test-server", - command=None, - args=None, - env=["NEW_KEY=new_value"], # Only env provided - url=None, - header=None, - timeout=None, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - - # Validate: configure_server was called with merged config - mock_manager.configure_server.assert_called_once() - call_args = mock_manager.configure_server.call_args - omni_config = call_args[1]['server_config'] - - # Env should be updated - self.assertEqual(omni_config.env, {"NEW_KEY": "new_value"}) - # Other fields should be preserved - self.assertEqual(omni_config.command, "python") - self.assertEqual(omni_config.args, ["server.py"]) - - @regression_test - def test_configure_create_requires_command_or_url(self): - """Test B4: Create operation requires command or url.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = None # Server doesn't exist - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Create without command or url - result = handle_mcp_configure( - host="claude-desktop", - server_name="new-server", - command=None, # No command - args=None, - env=None, - url=None, # No url - header=None, - timeout=60, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should fail with error - self.assertEqual(result, 1) - - # Validate: Error message mentions command or url - mock_print.assert_called() - error_message = str(mock_print.call_args[0][0]) - self.assertIn("command", error_message.lower()) - self.assertIn("url", error_message.lower()) - - @regression_test - def test_configure_update_allows_no_command_url(self): - """Test B5: Update operation allows omitting command/url.""" - # Setup: Existing server with command - existing_server = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"] - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Update without command or url - result = handle_mcp_configure( - host="claude-desktop", - server_name="test-server", - command=None, # No command - args=None, - env=None, - url=None, # No url - header=None, - timeout=60, # Only timeout - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - - # Validate: Command should be preserved - mock_manager.configure_server.assert_called_once() - call_args = mock_manager.configure_server.call_args - omni_config = call_args[1]['server_config'] - self.assertEqual(omni_config.command, "python") - - -class TestFieldPreservation(unittest.TestCase): - """Test suite for field preservation verification (Category C).""" - - @regression_test - def test_configure_update_preserves_unspecified_fields(self): - """Test C1: Unspecified fields remain unchanged during update.""" - # Setup: Existing server with multiple fields - existing_server = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"], - env={"API_KEY": "test_key"}, - timeout=30 - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Update only timeout (use Gemini which supports timeout) - result = handle_mcp_configure( - host="gemini", - server_name="test-server", - command=None, - args=None, - env=None, - url=None, - header=None, - timeout=60, # Only timeout updated - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - host_config = call_args[1]['server_config'] - - # Timeout updated (Gemini supports timeout) - self.assertEqual(host_config.timeout, 60) - # All other fields preserved - self.assertEqual(host_config.command, "python") - self.assertEqual(host_config.args, ["server.py"]) - self.assertEqual(host_config.env, {"API_KEY": "test_key"}) - - @regression_test - def test_configure_update_dependent_fields(self): - """Test C3+C4: Update dependent fields without parent field.""" - # Scenario 1: Update args without command - existing_cmd_server = MCPServerConfig( - name="cmd-server", - command="python", - args=["old.py"] - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_cmd_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Update args without command - result = handle_mcp_configure( - host="claude-desktop", - server_name="cmd-server", - command=None, # Command not provided - args=["new.py"], # Args updated - env=None, - url=None, - header=None, - timeout=None, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - omni_config = call_args[1]['server_config'] - - # Args updated, command preserved - self.assertEqual(omni_config.args, ["new.py"]) - self.assertEqual(omni_config.command, "python") - - # Scenario 2: Update headers without url - existing_url_server = MCPServerConfig( - name="url-server", - url="http://localhost:8080", - headers={"Authorization": "Bearer old_token"} - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_url_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Update headers without url - result = handle_mcp_configure( - host="claude-desktop", - server_name="url-server", - command=None, - args=None, - env=None, - url=None, # URL not provided - header=["Authorization=Bearer new_token"], # Headers updated - timeout=None, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - omni_config = call_args[1]['server_config'] - - # Headers updated, url preserved - self.assertEqual(omni_config.headers, {"Authorization": "Bearer new_token"}) - self.assertEqual(omni_config.url, "http://localhost:8080") - - -class TestCommandUrlSwitching(unittest.TestCase): - """Test suite for command/URL switching behavior (Category E) [CRITICAL].""" - - @regression_test - def test_configure_switch_command_to_url(self): - """Test E1: Switch from command-based to URL-based server [CRITICAL].""" - # Setup: Existing command-based server - existing_server = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"], - env={"API_KEY": "test_key"} - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Switch to URL-based (use gemini which supports URL) - result = handle_mcp_configure( - host="gemini", - server_name="test-server", - command=None, - args=None, - env=None, - url="http://localhost:8080", # Provide URL - header=["Authorization=Bearer token"], # Provide headers - timeout=None, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - omni_config = call_args[1]['server_config'] - - # URL-based fields set - self.assertEqual(omni_config.url, "http://localhost:8080") - self.assertEqual(omni_config.headers, {"Authorization": "Bearer token"}) - # Command-based fields cleared - self.assertIsNone(omni_config.command) - self.assertIsNone(omni_config.args) - # Type field updated to 'sse' (Issue 1) - self.assertEqual(omni_config.type, "sse") - - @regression_test - def test_configure_switch_url_to_command(self): - """Test E2: Switch from URL-based to command-based server [CRITICAL].""" - # Setup: Existing URL-based server - existing_server = MCPServerConfig( - name="test-server", - url="http://localhost:8080", - headers={"Authorization": "Bearer token"} - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Switch to command-based (use gemini which supports both) - result = handle_mcp_configure( - host="gemini", - server_name="test-server", - command="node", # Provide command - args=["server.js"], # Provide args - env=None, - url=None, - header=None, - timeout=None, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - call_args = mock_manager.configure_server.call_args - omni_config = call_args[1]['server_config'] - - # Command-based fields set - self.assertEqual(omni_config.command, "node") - self.assertEqual(omni_config.args, ["server.js"]) - # URL-based fields cleared - self.assertIsNone(omni_config.url) - self.assertIsNone(omni_config.headers) - # Type field updated to 'stdio' (Issue 1) - self.assertEqual(omni_config.type, "stdio") - - -class TestPartialUpdateIntegration(unittest.TestCase): - """Test suite for end-to-end partial update workflows (Integration Tests).""" - - @integration_test(scope="component") - def test_partial_update_end_to_end_timeout(self): - """Test I1: End-to-end partial update workflow for timeout field.""" - # Setup: Existing server - existing_server = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"], - timeout=30 - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - with patch('hatch.cli_hatch.generate_conversion_report') as mock_report: - # Mock report to verify UNCHANGED detection - mock_report.return_value = MagicMock() - - # Execute: Full CLI workflow - result = handle_mcp_configure( - host="claude-desktop", - server_name="test-server", - command=None, - args=None, - env=None, - url=None, - header=None, - timeout=60, # Update timeout only - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - - # Validate: Report was generated with old_config for UNCHANGED detection - mock_report.assert_called_once() - call_kwargs = mock_report.call_args[1] - self.assertEqual(call_kwargs['operation'], 'update') - self.assertIsNotNone(call_kwargs.get('old_config')) - - @integration_test(scope="component") - def test_partial_update_end_to_end_switch_type(self): - """Test I2: End-to-end workflow for command/URL switching.""" - # Setup: Existing command-based server - existing_server = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"] - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - with patch('hatch.cli_hatch.generate_conversion_report') as mock_report: - mock_report.return_value = MagicMock() - - # Execute: Switch to URL-based (use gemini which supports URL) - result = handle_mcp_configure( - host="gemini", - server_name="test-server", - command=None, - args=None, - env=None, - url="http://localhost:8080", - header=["Authorization=Bearer token"], - timeout=None, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - - # Validate: Server type switched - call_args = mock_manager.configure_server.call_args - omni_config = call_args[1]['server_config'] - self.assertEqual(omni_config.url, "http://localhost:8080") - self.assertIsNone(omni_config.command) - - -class TestBackwardCompatibility(unittest.TestCase): - """Test suite for backward compatibility (Regression Tests).""" - - @regression_test - def test_existing_create_operation_unchanged(self): - """Test R1: Existing create operations work identically.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = None # Server doesn't exist - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Create operation with full configuration (use Gemini for timeout support) - result = handle_mcp_configure( - host="gemini", - server_name="new-server", - command="python", - args=["server.py"], - env=["API_KEY=secret"], - url=None, - header=None, - timeout=30, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - - # Validate: Server created with all fields - mock_manager.configure_server.assert_called_once() - call_args = mock_manager.configure_server.call_args - host_config = call_args[1]['server_config'] - self.assertEqual(host_config.command, "python") - self.assertEqual(host_config.args, ["server.py"]) - self.assertEqual(host_config.timeout, 30) - - @regression_test - def test_error_messages_remain_clear(self): - """Test R2: Error messages are clear and helpful (modified).""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = None # Server doesn't exist - - with patch('hatch.cli_hatch.print') as mock_print: - # Execute: Create without command or url - result = handle_mcp_configure( - host="claude-desktop", - server_name="new-server", - command=None, # No command - args=None, - env=None, - url=None, # No url - header=None, - timeout=60, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should fail - self.assertEqual(result, 1) - - # Validate: Error message is clear - mock_print.assert_called() - error_message = str(mock_print.call_args[0][0]) - self.assertIn("command", error_message.lower()) - self.assertIn("url", error_message.lower()) - # Should mention this is for creating a new server - self.assertTrue( - "creat" in error_message.lower() or "new" in error_message.lower(), - f"Error message should clarify this is for creating: {error_message}" - ) - - -class TestTypeFieldUpdating(unittest.TestCase): - """Test suite for type field updates during transport switching (Issue 1).""" - - @regression_test - def test_type_field_updates_command_to_url(self): - """Test type field updates from 'stdio' to 'sse' when switching to URL.""" - # Setup: Create existing command-based server with type='stdio' - existing_server = MCPServerConfig( - name="test-server", - type="stdio", - command="python", - args=["server.py"] - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print'): - # Execute: Switch to URL-based configuration - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command=None, - args=None, - env=None, - url='http://localhost:8080', - header=None, - timeout=None, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - - # Validate: Type field updated to 'sse' - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertEqual(server_config.type, "sse") - self.assertIsNone(server_config.command) - self.assertEqual(server_config.url, "http://localhost:8080") - - @regression_test - def test_type_field_updates_url_to_command(self): - """Test type field updates from 'sse' to 'stdio' when switching to command.""" - # Setup: Create existing URL-based server with type='sse' - existing_server = MCPServerConfig( - name="test-server", - type="sse", - url="http://localhost:8080", - headers={"Authorization": "Bearer token"} - ) - - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_manager_class.return_value = mock_manager - mock_manager.get_server_config.return_value = existing_server - mock_manager.configure_server.return_value = MagicMock(success=True) - - with patch('hatch.cli_hatch.print'): - # Execute: Switch to command-based configuration - result = handle_mcp_configure( - host='gemini', - server_name='test-server', - command='python', - args=['server.py'], - env=None, - url=None, - header=None, - timeout=None, - trust=False, - cwd=None, - env_file=None, - http_url=None, - include_tools=None, - exclude_tools=None, - input=None, - no_backup=False, - dry_run=False, - auto_approve=True - ) - - # Validate: Should succeed - self.assertEqual(result, 0) - - # Validate: Type field updated to 'stdio' - call_args = mock_manager.configure_server.call_args - server_config = call_args.kwargs['server_config'] - self.assertEqual(server_config.type, "stdio") - self.assertEqual(server_config.command, "python") - self.assertIsNone(server_config.url) - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/test_mcp_environment_integration.py b/tests/test_mcp_environment_integration.py deleted file mode 100644 index 47f14a0..0000000 --- a/tests/test_mcp_environment_integration.py +++ /dev/null @@ -1,520 +0,0 @@ -""" -Test suite for MCP environment integration. - -This module tests the integration between environment data and MCP host configuration -with the corrected data structure. -""" - -import unittest -import sys -from pathlib import Path -from datetime import datetime -from unittest.mock import MagicMock, patch -import json - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import regression_test, integration_test -except ImportError: - # Fallback decorators if wobble is not available - def regression_test(func): - return func - - def integration_test(scope="component"): - def decorator(func): - return func - return decorator - -from test_data_utils import MCPHostConfigTestDataLoader -from hatch.mcp_host_config.models import ( - MCPServerConfig, EnvironmentData, EnvironmentPackageEntry, - PackageHostConfiguration, MCPHostType -) -from hatch.environment_manager import HatchEnvironmentManager - - -class TestMCPEnvironmentIntegration(unittest.TestCase): - """Test suite for MCP environment integration with corrected structure.""" - - def setUp(self): - """Set up test environment.""" - self.test_data_loader = MCPHostConfigTestDataLoader() - - @regression_test - def test_environment_data_validation_success(self): - """Test successful environment data validation.""" - env_data = self.test_data_loader.load_corrected_environment_data("simple") - environment = EnvironmentData(**env_data) - - self.assertEqual(environment.name, "test_environment") - self.assertEqual(len(environment.packages), 1) - - package = environment.packages[0] - self.assertEqual(package.name, "weather-toolkit") - self.assertEqual(package.version, "1.0.0") - self.assertIn("claude-desktop", package.configured_hosts) - - host_config = package.configured_hosts["claude-desktop"] - self.assertIsInstance(host_config, PackageHostConfiguration) - self.assertIsInstance(host_config.server_config, MCPServerConfig) - - @regression_test - def test_environment_data_multi_host_validation(self): - """Test environment data validation with multiple hosts.""" - env_data = self.test_data_loader.load_corrected_environment_data("multi_host") - environment = EnvironmentData(**env_data) - - self.assertEqual(environment.name, "multi_host_environment") - self.assertEqual(len(environment.packages), 1) - - package = environment.packages[0] - self.assertEqual(package.name, "file-manager") - self.assertEqual(len(package.configured_hosts), 2) - self.assertIn("claude-desktop", package.configured_hosts) - self.assertIn("cursor", package.configured_hosts) - - # Verify both host configurations - claude_config = package.configured_hosts["claude-desktop"] - cursor_config = package.configured_hosts["cursor"] - - self.assertIsInstance(claude_config, PackageHostConfiguration) - self.assertIsInstance(cursor_config, PackageHostConfiguration) - - # Verify server configurations are different for different hosts - self.assertEqual(claude_config.server_config.command, "/usr/local/bin/python") - self.assertEqual(cursor_config.server_config.command, "python") - - @regression_test - def test_package_host_configuration_validation(self): - """Test package host configuration validation.""" - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - - host_config = PackageHostConfiguration( - config_path="~/test/config.json", - configured_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - last_synced=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - server_config=server_config - ) - - self.assertEqual(host_config.config_path, "~/test/config.json") - self.assertIsInstance(host_config.server_config, MCPServerConfig) - self.assertEqual(host_config.server_config.command, "python") - self.assertEqual(len(host_config.server_config.args), 3) - - @regression_test - def test_environment_package_entry_validation_success(self): - """Test successful environment package entry validation.""" - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - - host_config = PackageHostConfiguration( - config_path="~/test/config.json", - configured_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - last_synced=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - server_config=server_config - ) - - package = EnvironmentPackageEntry( - name="test-package", - version="1.0.0", - type="hatch", - source="github:user/test-package", - installed_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - configured_hosts={"claude-desktop": host_config} - ) - - self.assertEqual(package.name, "test-package") - self.assertEqual(package.version, "1.0.0") - self.assertEqual(package.type, "hatch") - self.assertEqual(len(package.configured_hosts), 1) - self.assertIn("claude-desktop", package.configured_hosts) - - @regression_test - def test_environment_package_entry_invalid_host_name(self): - """Test environment package entry validation with invalid host name.""" - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - - host_config = PackageHostConfiguration( - config_path="~/test/config.json", - configured_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - last_synced=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - server_config=server_config - ) - - with self.assertRaises(Exception) as context: - EnvironmentPackageEntry( - name="test-package", - version="1.0.0", - type="hatch", - source="github:user/test-package", - installed_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - configured_hosts={"invalid-host": host_config} # Invalid host name - ) - - self.assertIn("Unsupported host", str(context.exception)) - - @regression_test - def test_environment_package_entry_invalid_package_name(self): - """Test environment package entry validation with invalid package name.""" - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - - host_config = PackageHostConfiguration( - config_path="~/test/config.json", - configured_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - last_synced=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - server_config=server_config - ) - - with self.assertRaises(Exception) as context: - EnvironmentPackageEntry( - name="invalid@package!name", # Invalid characters - version="1.0.0", - type="hatch", - source="github:user/test-package", - installed_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - configured_hosts={"claude-desktop": host_config} - ) - - self.assertIn("Invalid package name format", str(context.exception)) - - @regression_test - def test_environment_data_get_mcp_packages(self): - """Test getting MCP packages from environment data.""" - env_data = self.test_data_loader.load_corrected_environment_data("multi_host") - environment = EnvironmentData(**env_data) - - mcp_packages = environment.get_mcp_packages() - - self.assertEqual(len(mcp_packages), 1) - self.assertEqual(mcp_packages[0].name, "file-manager") - self.assertEqual(len(mcp_packages[0].configured_hosts), 2) - - @regression_test - def test_environment_data_serialization_roundtrip(self): - """Test environment data serialization and deserialization.""" - env_data = self.test_data_loader.load_corrected_environment_data("simple") - environment = EnvironmentData(**env_data) - - # Serialize and deserialize - serialized = environment.model_dump() - roundtrip_environment = EnvironmentData(**serialized) - - self.assertEqual(environment.name, roundtrip_environment.name) - self.assertEqual(len(environment.packages), len(roundtrip_environment.packages)) - - original_package = environment.packages[0] - roundtrip_package = roundtrip_environment.packages[0] - - self.assertEqual(original_package.name, roundtrip_package.name) - self.assertEqual(original_package.version, roundtrip_package.version) - self.assertEqual(len(original_package.configured_hosts), len(roundtrip_package.configured_hosts)) - - # Verify host configuration roundtrip - original_host_config = original_package.configured_hosts["claude-desktop"] - roundtrip_host_config = roundtrip_package.configured_hosts["claude-desktop"] - - self.assertEqual(original_host_config.config_path, roundtrip_host_config.config_path) - self.assertEqual(original_host_config.server_config.command, roundtrip_host_config.server_config.command) - - @regression_test - def test_corrected_environment_structure_single_server_per_package(self): - """Test that corrected environment structure enforces single server per package.""" - env_data = self.test_data_loader.load_corrected_environment_data("simple") - environment = EnvironmentData(**env_data) - - # Verify single server per package constraint - for package in environment.packages: - # Each package should have one server configuration per host - for host_name, host_config in package.configured_hosts.items(): - self.assertIsInstance(host_config, PackageHostConfiguration) - self.assertIsInstance(host_config.server_config, MCPServerConfig) - - # The server configuration should be for this specific package - # (In real usage, the server would be the package's MCP server) - - @regression_test - def test_environment_data_json_serialization(self): - """Test JSON serialization compatibility.""" - import json - - env_data = self.test_data_loader.load_corrected_environment_data("simple") - environment = EnvironmentData(**env_data) - - # Test JSON serialization - json_str = environment.model_dump_json() - self.assertIsInstance(json_str, str) - - # Test JSON deserialization - parsed_data = json.loads(json_str) - roundtrip_environment = EnvironmentData(**parsed_data) - - self.assertEqual(environment.name, roundtrip_environment.name) - self.assertEqual(len(environment.packages), len(roundtrip_environment.packages)) - - -class TestMCPHostTypeIntegration(unittest.TestCase): - """Test suite for MCP host type integration.""" - - @regression_test - def test_mcp_host_type_enum_values(self): - """Test MCP host type enum values.""" - # Verify all expected host types are available - expected_hosts = [ - "claude-desktop", "claude-code", "vscode", - "cursor", "lmstudio", "gemini" - ] - - for host_name in expected_hosts: - host_type = MCPHostType(host_name) - self.assertEqual(host_type.value, host_name) - - @regression_test - def test_mcp_host_type_invalid_value(self): - """Test MCP host type with invalid value.""" - with self.assertRaises(ValueError): - MCPHostType("invalid-host") - - -class TestEnvironmentManagerHostSync(unittest.TestCase): - """Test suite for EnvironmentManager host synchronization methods.""" - - def setUp(self): - """Set up test fixtures.""" - self.mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - - # Load test fixture data - fixture_path = Path(__file__).parent / "test_data" / "fixtures" / "host_sync_scenarios.json" - with open(fixture_path, 'r') as f: - self.test_data = json.load(f) - - @regression_test - def test_remove_package_host_configuration_success(self): - """Test successful removal of host from package tracking. - - Validates: - - Removes specified host from package's configured_hosts - - Updates environments.json file via _save_environments() - - Returns True when removal occurs - - Logs successful removal with package/host details - """ - # Setup: Environment with package having configured_hosts for multiple hosts - env_manager = HatchEnvironmentManager() - env_manager._environments = { - "test-env": self.test_data["remove_server_scenario"]["before"] - } - - with patch.object(env_manager, '_save_environments') as mock_save: - with patch.object(env_manager, 'logger') as mock_logger: - # Action: remove_package_host_configuration(env_name, package_name, hostname) - result = env_manager.remove_package_host_configuration("test-env", "weather-toolkit", "cursor") - - # Assert: Host removed from package, environments.json updated, returns True - self.assertTrue(result) - mock_save.assert_called_once() - mock_logger.info.assert_called_with("Removed host cursor from package weather-toolkit in env test-env") - - # Verify host was actually removed - packages = env_manager._environments["test-env"]["packages"] - weather_pkg = next(pkg for pkg in packages if pkg["name"] == "weather-toolkit") - self.assertNotIn("cursor", weather_pkg["configured_hosts"]) - self.assertIn("claude-desktop", weather_pkg["configured_hosts"]) - - @regression_test - def test_remove_package_host_configuration_not_found(self): - """Test removal when package or host not found. - - Validates: - - Returns False when environment doesn't exist - - Returns False when package not found in environment - - Returns False when host not in package's configured_hosts - - No changes to environments.json when nothing to remove - """ - env_manager = HatchEnvironmentManager() - env_manager._environments = { - "test-env": self.test_data["remove_server_scenario"]["before"] - } - - with patch.object(env_manager, '_save_environments') as mock_save: - # Test scenarios: missing env, missing package, missing host - - # Missing environment - result = env_manager.remove_package_host_configuration("missing-env", "weather-toolkit", "cursor") - self.assertFalse(result) - - # Missing package - result = env_manager.remove_package_host_configuration("test-env", "missing-package", "cursor") - self.assertFalse(result) - - # Missing host - result = env_manager.remove_package_host_configuration("test-env", "weather-toolkit", "missing-host") - self.assertFalse(result) - - # Assert: No file changes when nothing to remove - mock_save.assert_not_called() - - @regression_test - def test_clear_host_from_all_packages_all_envs(self): - """Test host removal across multiple environments. - - Validates: - - Iterates through all environments in _environments - - Removes hostname from all packages' configured_hosts - - Returns correct count of updated package entries - - Calls _save_environments() only once after all updates - """ - # Setup: Multiple environments with packages using same host - env_manager = HatchEnvironmentManager() - env_manager._environments = self.test_data["remove_host_scenario"]["multi_environment_before"] - - with patch.object(env_manager, '_save_environments') as mock_save: - with patch.object(env_manager, 'logger') as mock_logger: - # Action: clear_host_from_all_packages_all_envs(hostname) - updates_count = env_manager.clear_host_from_all_packages_all_envs("cursor") - - # Assert: Host removed from all packages, correct count returned - self.assertEqual(updates_count, 2) # 2 packages had cursor configured - mock_save.assert_called_once() - - # Verify cursor was removed from all packages - for env_name, env_data in env_manager._environments.items(): - for pkg in env_data["packages"]: - configured_hosts = pkg.get("configured_hosts", {}) - self.assertNotIn("cursor", configured_hosts) - - -class TestEnvironmentManagerHostSyncErrorHandling(unittest.TestCase): - """Test suite for error handling and edge cases.""" - - def setUp(self): - """Set up test fixtures.""" - self.env_manager = HatchEnvironmentManager() - - @regression_test - def test_remove_operations_exception_handling(self): - """Test exception handling in remove operations. - - Validates: - - Catches and logs exceptions during removal operations - - Returns False/0 on exceptions rather than crashing - - Provides meaningful error messages in logs - - Maintains environment file integrity on errors - """ - # Setup: Mock scenarios that raise exceptions - # Create environment with package that has the host, so _save_environments will be called - self.env_manager._environments = { - "test-env": { - "packages": [ - { - "name": "test-pkg", - "configured_hosts": { - "test-host": {"config_path": "test"} - } - } - ] - } - } - - with patch.object(self.env_manager, '_save_environments', side_effect=Exception("File error")): - with patch.object(self.env_manager, 'logger') as mock_logger: - # Action: Call remove methods with exception-inducing conditions - result = self.env_manager.remove_package_host_configuration("test-env", "test-pkg", "test-host") - - # Assert: Graceful error handling, no crashes, appropriate returns - self.assertFalse(result) - mock_logger.error.assert_called() - - -class TestCLIHostMutationSync(unittest.TestCase): - """Test suite for CLI integration with environment tracking.""" - - def setUp(self): - """Set up test fixtures.""" - self.mock_env_manager = MagicMock(spec=HatchEnvironmentManager) - - @integration_test(scope="component") - def test_remove_server_updates_environment(self): - """Test that remove server updates current environment tracking. - - Validates: - - CLI remove server calls environment manager update method - - Updates only current environment (not all environments) - - Passes correct parameters (env_name, server_name, hostname) - - Maintains existing CLI behavior and exit codes - """ - from hatch.cli_hatch import handle_mcp_remove_server - from hatch.mcp_host_config import MCPHostConfigurationManager - - # Setup: Environment with server configured on host - self.mock_env_manager.get_current_environment.return_value = "test-env" - - with patch.object(MCPHostConfigurationManager, 'remove_server') as mock_remove: - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_remove.return_value = mock_result - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - with patch('builtins.print'): - # Action: hatch mcp remove server --host - result = handle_mcp_remove_server( - self.mock_env_manager, "test-server", "claude-desktop", - None, False, False, True - ) - - # Assert: Environment manager method called with correct parameters - self.mock_env_manager.get_current_environment.assert_called_once() - self.mock_env_manager.remove_package_host_configuration.assert_called_with( - "test-env", "test-server", "claude-desktop" - ) - - # Assert: Success exit code - self.assertEqual(result, 0) - - @integration_test(scope="component") - def test_remove_host_updates_all_environments(self): - """Test that remove host updates all environment tracking. - - Validates: - - CLI remove host calls global environment update method - - Updates ALL environments (not just current) - - Passes correct hostname parameter - - Reports number of updates performed to user - """ - from hatch.cli_hatch import handle_mcp_remove_host - from hatch.mcp_host_config import MCPHostConfigurationManager - - # Setup: Multiple environments with packages using the host - with patch.object(MCPHostConfigurationManager, 'remove_host_configuration') as mock_remove: - mock_result = MagicMock() - mock_result.success = True - mock_result.backup_path = None - mock_remove.return_value = mock_result - - self.mock_env_manager.clear_host_from_all_packages_all_envs.return_value = 3 - - with patch('hatch.cli_hatch.request_confirmation', return_value=True): - with patch('builtins.print') as mock_print: - # Action: hatch mcp remove host - result = handle_mcp_remove_host( - self.mock_env_manager, "cursor", False, False, True - ) - - # Assert: Global environment update method called - self.mock_env_manager.clear_host_from_all_packages_all_envs.assert_called_with("cursor") - - # Assert: User informed of update count - print_calls = [call[0][0] for call in mock_print.call_args_list] - output = ' '.join(print_calls) - self.assertIn("Updated 3 package entries across environments", output) - - # Assert: Success exit code - self.assertEqual(result, 0) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_host_config_backup.py b/tests/test_mcp_host_config_backup.py deleted file mode 100644 index 55b5f5e..0000000 --- a/tests/test_mcp_host_config_backup.py +++ /dev/null @@ -1,257 +0,0 @@ -"""Tests for MCPHostConfigBackupManager. - -This module contains tests for the MCP host configuration backup functionality, -including backup creation, restoration, and management with host-agnostic design. -""" - -import unittest -import tempfile -import shutil -import json -from pathlib import Path -from datetime import datetime -from unittest.mock import patch, Mock - -from wobble.decorators import regression_test, integration_test, slow_test -from test_data_utils import MCPBackupTestDataLoader - -from hatch.mcp_host_config.backup import ( - MCPHostConfigBackupManager, - BackupInfo, - BackupResult, - BackupError -) - - -class TestMCPHostConfigBackupManager(unittest.TestCase): - """Test MCPHostConfigBackupManager core functionality with host-agnostic design.""" - - def setUp(self): - """Set up test environment with host-agnostic configurations.""" - self.temp_dir = Path(tempfile.mkdtemp(prefix="test_mcp_backup_")) - self.backup_root = self.temp_dir / "backups" - self.config_dir = self.temp_dir / "configs" - self.config_dir.mkdir(parents=True) - - # Initialize test data loader - self.test_data = MCPBackupTestDataLoader() - - # Create host-agnostic test configuration files - self.test_configs = {} - for hostname in ['claude-desktop', 'vscode', 'cursor', 'lmstudio']: - config_data = self.test_data.load_host_agnostic_config("simple_server") - config_file = self.config_dir / f"{hostname}_config.json" - with open(config_file, 'w') as f: - json.dump(config_data, f, indent=2) - self.test_configs[hostname] = config_file - - self.backup_manager = MCPHostConfigBackupManager(backup_root=self.backup_root) - - def tearDown(self): - """Clean up test environment.""" - shutil.rmtree(self.temp_dir, ignore_errors=True) - - @regression_test - def test_backup_directory_creation(self): - """Test automatic backup directory creation.""" - self.assertTrue(self.backup_root.exists()) - self.assertTrue(self.backup_root.is_dir()) - - @regression_test - def test_create_backup_success_all_hosts(self): - """Test successful backup creation for all supported host types.""" - for hostname, config_file in self.test_configs.items(): - with self.subTest(hostname=hostname): - result = self.backup_manager.create_backup(config_file, hostname) - - # Validate BackupResult Pydantic model - self.assertIsInstance(result, BackupResult) - self.assertTrue(result.success) - self.assertIsNotNone(result.backup_path) - self.assertTrue(result.backup_path.exists()) - self.assertGreater(result.backup_size, 0) - self.assertEqual(result.original_size, result.backup_size) - - # Verify backup filename format (host-agnostic) - expected_pattern = rf"mcp\.json\.{hostname}\.\d{{8}}_\d{{6}}_\d{{6}}" - self.assertRegex(result.backup_path.name, expected_pattern) - - @regression_test - def test_create_backup_nonexistent_file(self): - """Test backup creation with nonexistent source file.""" - nonexistent = self.config_dir / "nonexistent.json" - result = self.backup_manager.create_backup(nonexistent, "claude-desktop") - - self.assertFalse(result.success) - self.assertIsNotNone(result.error_message) - self.assertIn("not found", result.error_message.lower()) - - @regression_test - def test_backup_content_integrity_host_agnostic(self): - """Test backup content matches original for any host configuration format.""" - hostname = 'claude-desktop' - config_file = self.test_configs[hostname] - original_content = config_file.read_text() - - result = self.backup_manager.create_backup(config_file, hostname) - - self.assertTrue(result.success) - backup_content = result.backup_path.read_text() - self.assertEqual(original_content, backup_content) - - # Verify JSON structure is preserved (host-agnostic validation) - original_json = json.loads(original_content) - backup_json = json.loads(backup_content) - self.assertEqual(original_json, backup_json) - - @regression_test - def test_multiple_backups_same_host(self): - """Test creating multiple backups for same host.""" - hostname = 'vscode' - config_file = self.test_configs[hostname] - - # Create first backup - result1 = self.backup_manager.create_backup(config_file, hostname) - self.assertTrue(result1.success) - - # Modify config and create second backup - modified_config = self.test_data.load_host_agnostic_config("complex_server") - with open(config_file, 'w') as f: - json.dump(modified_config, f, indent=2) - - result2 = self.backup_manager.create_backup(config_file, hostname) - self.assertTrue(result2.success) - - # Verify both backups exist and are different - self.assertTrue(result1.backup_path.exists()) - self.assertTrue(result2.backup_path.exists()) - self.assertNotEqual(result1.backup_path, result2.backup_path) - - @regression_test - def test_list_backups_empty(self): - """Test listing backups when none exist.""" - backups = self.backup_manager.list_backups("claude-desktop") - self.assertEqual(len(backups), 0) - - @regression_test - def test_list_backups_pydantic_validation(self): - """Test listing backups returns valid Pydantic models.""" - hostname = 'cursor' - config_file = self.test_configs[hostname] - - # Create multiple backups - self.backup_manager.create_backup(config_file, hostname) - self.backup_manager.create_backup(config_file, hostname) - - backups = self.backup_manager.list_backups(hostname) - self.assertEqual(len(backups), 2) - - # Verify BackupInfo Pydantic model validation - for backup in backups: - self.assertIsInstance(backup, BackupInfo) - self.assertEqual(backup.hostname, hostname) - self.assertIsInstance(backup.timestamp, datetime) - self.assertTrue(backup.file_path.exists()) - self.assertGreater(backup.file_size, 0) - - # Test Pydantic serialization - backup_dict = backup.dict() - self.assertIn('hostname', backup_dict) - self.assertIn('timestamp', backup_dict) - - # Test JSON serialization - backup_json = backup.json() - self.assertIsInstance(backup_json, str) - - # Verify sorting (newest first) - self.assertGreaterEqual(backups[0].timestamp, backups[1].timestamp) - - @regression_test - def test_backup_validation_unsupported_hostname(self): - """Test Pydantic validation rejects unsupported hostnames.""" - config_file = self.test_configs['claude-desktop'] - - # Test with unsupported hostname - result = self.backup_manager.create_backup(config_file, 'unsupported-host') - - self.assertFalse(result.success) - self.assertIn('unsupported', result.error_message.lower()) - - @regression_test - def test_multiple_hosts_isolation(self): - """Test backup isolation between different host types.""" - # Create backups for multiple hosts - results = {} - for hostname, config_file in self.test_configs.items(): - results[hostname] = self.backup_manager.create_backup(config_file, hostname) - self.assertTrue(results[hostname].success) - - # Verify separate backup directories - for hostname in self.test_configs.keys(): - backups = self.backup_manager.list_backups(hostname) - self.assertEqual(len(backups), 1) - - # Verify backup isolation (different directories) - backup_dir = backups[0].file_path.parent - self.assertEqual(backup_dir.name, hostname) - - # Verify no cross-contamination - for other_hostname in self.test_configs.keys(): - if other_hostname != hostname: - other_backups = self.backup_manager.list_backups(other_hostname) - self.assertNotEqual( - backups[0].file_path.parent, - other_backups[0].file_path.parent - ) - - @regression_test - def test_clean_backups_older_than_days(self): - """Test cleaning backups older than specified days.""" - hostname = 'lmstudio' - config_file = self.test_configs[hostname] - - # Create backup - result = self.backup_manager.create_backup(config_file, hostname) - self.assertTrue(result.success) - - # Mock old backup by modifying timestamp - old_backup_path = result.backup_path.parent / "mcp.json.lmstudio.20200101_120000_000000" - shutil.copy2(result.backup_path, old_backup_path) - - # Clean backups older than 1 day (should remove the old one) - cleaned_count = self.backup_manager.clean_backups(hostname, older_than_days=1) - - # Verify old backup was cleaned - self.assertGreater(cleaned_count, 0) - self.assertFalse(old_backup_path.exists()) - self.assertTrue(result.backup_path.exists()) # Recent backup should remain - - @regression_test - def test_clean_backups_keep_count(self): - """Test cleaning backups to keep only specified count.""" - hostname = 'claude-desktop' - config_file = self.test_configs[hostname] - - # Create multiple backups - for i in range(5): - self.backup_manager.create_backup(config_file, hostname) - - # Verify 5 backups exist - backups_before = self.backup_manager.list_backups(hostname) - self.assertEqual(len(backups_before), 5) - - # Clean to keep only 2 backups - cleaned_count = self.backup_manager.clean_backups(hostname, keep_count=2) - - # Verify only 2 backups remain - backups_after = self.backup_manager.list_backups(hostname) - self.assertEqual(len(backups_after), 2) - self.assertEqual(cleaned_count, 3) - - # Verify newest backups were kept - for backup in backups_after: - self.assertIn(backup, backups_before[:2]) # Should be the first 2 (newest) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_host_configuration_manager.py b/tests/test_mcp_host_configuration_manager.py deleted file mode 100644 index 9ff6d46..0000000 --- a/tests/test_mcp_host_configuration_manager.py +++ /dev/null @@ -1,331 +0,0 @@ -""" -Test suite for MCP host configuration manager. - -This module tests the core configuration manager with consolidated models -and integration with backup system. -""" - -import unittest -import sys -from pathlib import Path -import tempfile -import json -import os - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import regression_test, integration_test -except ImportError: - # Fallback decorators if wobble is not available - def regression_test(func): - return func - - def integration_test(scope="component"): - def decorator(func): - return func - return decorator - -from test_data_utils import MCPHostConfigTestDataLoader -from hatch.mcp_host_config.host_management import MCPHostConfigurationManager, MCPHostRegistry, register_host_strategy -from hatch.mcp_host_config.models import MCPHostType, MCPServerConfig, HostConfiguration, ConfigurationResult, SyncResult -from hatch.mcp_host_config.strategies import MCPHostStrategy - - -class TestMCPHostConfigurationManager(unittest.TestCase): - """Test suite for MCP host configuration manager.""" - - def setUp(self): - """Set up test environment.""" - self.test_data_loader = MCPHostConfigTestDataLoader() - self.temp_dir = tempfile.mkdtemp() - self.temp_config_path = Path(self.temp_dir) / "test_config.json" - - # Clear registry before each test - MCPHostRegistry._strategies.clear() - MCPHostRegistry._instances.clear() - - # Store temp_config_path for strategy access - temp_config_path = self.temp_config_path - - # Register test strategy - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class TestStrategy(MCPHostStrategy): - def get_config_path(self): - return temp_config_path - - def is_host_available(self): - return True - - def read_configuration(self): - if temp_config_path.exists(): - with open(temp_config_path, 'r') as f: - data = json.load(f) - - servers = {} - if "mcpServers" in data: - for name, config in data["mcpServers"].items(): - servers[name] = MCPServerConfig(**config) - - return HostConfiguration(servers=servers) - else: - return HostConfiguration(servers={}) - - def write_configuration(self, config, no_backup=False): - try: - # Convert MCPServerConfig objects to dict - servers_dict = {} - for name, server_config in config.servers.items(): - servers_dict[name] = server_config.model_dump(exclude_none=True) - - # Create configuration data - config_data = {"mcpServers": servers_dict} - - # Write to file - with open(temp_config_path, 'w') as f: - json.dump(config_data, f, indent=2) - - return True - except Exception: - return False - - def validate_server_config(self, server_config): - return True - - self.manager = MCPHostConfigurationManager() - self.temp_config_path = self.temp_config_path - - def tearDown(self): - """Clean up test environment.""" - # Clean up temp files - if self.temp_config_path.exists(): - self.temp_config_path.unlink() - os.rmdir(self.temp_dir) - - # Clear registry after each test - MCPHostRegistry._strategies.clear() - MCPHostRegistry._instances.clear() - - @regression_test - def test_configure_server_success(self): - """Test successful server configuration.""" - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - # Add name attribute for the manager to use - server_config.name = "test_server" - - result = self.manager.configure_server( - server_config=server_config, - hostname="claude-desktop" - ) - - self.assertIsInstance(result, ConfigurationResult) - if not result.success: - print(f"Configuration failed: {result.error_message}") - self.assertTrue(result.success) - self.assertIsNone(result.error_message) - self.assertEqual(result.hostname, "claude-desktop") - self.assertEqual(result.server_name, "test_server") - - # Verify configuration was written - self.assertTrue(self.temp_config_path.exists()) - - # Verify configuration content - with open(self.temp_config_path, 'r') as f: - config_data = json.load(f) - - self.assertIn("mcpServers", config_data) - self.assertIn("test_server", config_data["mcpServers"]) - self.assertEqual(config_data["mcpServers"]["test_server"]["command"], "python") - - @regression_test - def test_configure_server_unknown_host_type(self): - """Test configuration with unknown host type.""" - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - server_config.name = "test_server" - - # Clear registry to simulate unknown host type - MCPHostRegistry._strategies.clear() - - result = self.manager.configure_server( - server_config=server_config, - hostname="claude-desktop" - ) - - self.assertIsInstance(result, ConfigurationResult) - self.assertFalse(result.success) - self.assertIsNotNone(result.error_message) - self.assertIn("Unknown host type", result.error_message) - - @regression_test - def test_configure_server_validation_failure(self): - """Test configuration with validation failure.""" - # Create server config that will fail validation at the strategy level - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - server_config.name = "test_server" - - # Override the test strategy to always fail validation - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class FailingValidationStrategy(MCPHostStrategy): - def get_config_path(self): - return self.temp_config_path - - def is_host_available(self): - return True - - def read_configuration(self): - return HostConfiguration(servers={}) - - def write_configuration(self, config, no_backup=False): - return True - - def validate_server_config(self, server_config): - return False # Always fail validation - - result = self.manager.configure_server( - server_config=server_config, - hostname="claude-desktop" - ) - - self.assertIsInstance(result, ConfigurationResult) - self.assertFalse(result.success) - self.assertIsNotNone(result.error_message) - self.assertIn("Server configuration invalid", result.error_message) - - @regression_test - def test_remove_server_success(self): - """Test successful server removal.""" - # First configure a server - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - server_config.name = "test_server" - - self.manager.configure_server( - server_config=server_config, - hostname="claude-desktop" - ) - - # Verify server exists - with open(self.temp_config_path, 'r') as f: - config_data = json.load(f) - self.assertIn("test_server", config_data["mcpServers"]) - - # Remove server - result = self.manager.remove_server( - server_name="test_server", - hostname="claude-desktop" - ) - - self.assertIsInstance(result, ConfigurationResult) - self.assertTrue(result.success) - self.assertIsNone(result.error_message) - - # Verify server was removed - with open(self.temp_config_path, 'r') as f: - config_data = json.load(f) - self.assertNotIn("test_server", config_data["mcpServers"]) - - @regression_test - def test_remove_server_not_found(self): - """Test removing non-existent server.""" - result = self.manager.remove_server( - server_name="nonexistent_server", - hostname="claude-desktop" - ) - - self.assertIsInstance(result, ConfigurationResult) - self.assertFalse(result.success) - self.assertIsNotNone(result.error_message) - self.assertIn("Server 'nonexistent_server' not found", result.error_message) - - @regression_test - def test_sync_environment_to_hosts_success(self): - """Test successful environment synchronization.""" - from hatch.mcp_host_config.models import EnvironmentData, EnvironmentPackageEntry, PackageHostConfiguration - from datetime import datetime - - # Create test environment data - server_config_data = self.test_data_loader.load_mcp_server_config("local") - server_config = MCPServerConfig(**server_config_data) - - host_config = PackageHostConfiguration( - config_path="~/test/config.json", - configured_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - last_synced=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - server_config=server_config - ) - - package = EnvironmentPackageEntry( - name="test-package", - version="1.0.0", - type="hatch", - source="github:user/test-package", - installed_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - configured_hosts={"claude-desktop": host_config} - ) - - env_data = EnvironmentData( - name="test_env", - description="Test environment", - created_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - packages=[package] - ) - - # Sync environment to hosts - result = self.manager.sync_environment_to_hosts( - env_data=env_data, - target_hosts=["claude-desktop"] - ) - - self.assertIsInstance(result, SyncResult) - self.assertTrue(result.success) - self.assertEqual(result.servers_synced, 1) - self.assertEqual(result.hosts_updated, 1) - self.assertEqual(len(result.results), 1) - - # Verify configuration was written - self.assertTrue(self.temp_config_path.exists()) - - # Verify configuration content - with open(self.temp_config_path, 'r') as f: - config_data = json.load(f) - - self.assertIn("mcpServers", config_data) - self.assertIn("test-package", config_data["mcpServers"]) - self.assertEqual(config_data["mcpServers"]["test-package"]["command"], "python") - - @regression_test - def test_sync_environment_to_hosts_no_servers(self): - """Test environment synchronization with no servers.""" - from hatch.mcp_host_config.models import EnvironmentData - from datetime import datetime - - # Create empty environment data - env_data = EnvironmentData( - name="empty_env", - description="Empty environment", - created_at=datetime.fromisoformat("2025-09-21T10:00:00.000000"), - packages=[] - ) - - # Sync environment to hosts - result = self.manager.sync_environment_to_hosts( - env_data=env_data, - target_hosts=["claude-desktop"] - ) - - self.assertIsInstance(result, SyncResult) - self.assertTrue(result.success) # Success even with no servers - self.assertEqual(result.servers_synced, 0) - self.assertEqual(result.hosts_updated, 1) - self.assertEqual(len(result.results), 1) - - # Verify result message - self.assertEqual(result.results[0].error_message, "No servers to sync") - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_host_registry_decorator.py b/tests/test_mcp_host_registry_decorator.py deleted file mode 100644 index 2bc88ed..0000000 --- a/tests/test_mcp_host_registry_decorator.py +++ /dev/null @@ -1,348 +0,0 @@ -""" -Test suite for decorator-based host registry. - -This module tests the decorator-based strategy registration system -following Hatchling patterns with inheritance validation. -""" - -import unittest -import sys -from pathlib import Path - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import regression_test, integration_test -except ImportError: - # Fallback decorators if wobble is not available - def regression_test(func): - return func - - def integration_test(scope="component"): - def decorator(func): - return func - return decorator - -from hatch.mcp_host_config.host_management import MCPHostRegistry, register_host_strategy, MCPHostStrategy -from hatch.mcp_host_config.models import MCPHostType, MCPServerConfig, HostConfiguration -from pathlib import Path - - -class TestMCPHostRegistryDecorator(unittest.TestCase): - """Test suite for decorator-based host registry.""" - - def setUp(self): - """Set up test environment.""" - # Clear registry before each test - MCPHostRegistry._strategies.clear() - MCPHostRegistry._instances.clear() - - def tearDown(self): - """Clean up test environment.""" - # Clear registry after each test - MCPHostRegistry._strategies.clear() - MCPHostRegistry._instances.clear() - - @regression_test - def test_decorator_registration_functionality(self): - """Test that decorator registration works correctly.""" - - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class TestClaudeStrategy(MCPHostStrategy): - def get_config_path(self): - return Path("/test/path") - def is_host_available(self): - return True - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - def validate_server_config(self, server_config): - return True - - # Verify registration - self.assertIn(MCPHostType.CLAUDE_DESKTOP, MCPHostRegistry._strategies) - self.assertEqual( - MCPHostRegistry._strategies[MCPHostType.CLAUDE_DESKTOP], - TestClaudeStrategy - ) - - # Verify instance creation - strategy = MCPHostRegistry.get_strategy(MCPHostType.CLAUDE_DESKTOP) - self.assertIsInstance(strategy, TestClaudeStrategy) - - @regression_test - def test_decorator_registration_with_inheritance(self): - """Test decorator registration with inheritance patterns.""" - - class TestClaudeBase(MCPHostStrategy): - def __init__(self): - self.company_origin = "Anthropic" - self.config_format = "claude_format" - - def get_config_key(self): - return "mcpServers" - - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class TestClaudeDesktop(TestClaudeBase): - def get_config_path(self): - return Path("/test/claude") - def is_host_available(self): - return True - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - def validate_server_config(self, server_config): - return True - - strategy = MCPHostRegistry.get_strategy(MCPHostType.CLAUDE_DESKTOP) - - # Verify inheritance properties - self.assertEqual(strategy.company_origin, "Anthropic") - self.assertEqual(strategy.config_format, "claude_format") - self.assertEqual(strategy.get_config_key(), "mcpServers") - self.assertIsInstance(strategy, TestClaudeBase) - - @regression_test - def test_decorator_registration_duplicate_warning(self): - """Test warning on duplicate strategy registration.""" - import logging - - class BaseTestStrategy(MCPHostStrategy): - def get_config_path(self): - return Path("/test") - def is_host_available(self): - return True - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - def validate_server_config(self, server_config): - return True - - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class FirstStrategy(BaseTestStrategy): - pass - - # Register second strategy for same host type - should log warning - with self.assertLogs('hatch.mcp_host_config.host_management', level='WARNING') as log: - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class SecondStrategy(BaseTestStrategy): - pass - - # Verify warning was logged - self.assertTrue(any("Overriding existing strategy" in message for message in log.output)) - - # Verify second strategy is now registered - strategy = MCPHostRegistry.get_strategy(MCPHostType.CLAUDE_DESKTOP) - self.assertIsInstance(strategy, SecondStrategy) - - @regression_test - def test_decorator_registration_inheritance_validation(self): - """Test that decorator validates inheritance from MCPHostStrategy.""" - - # Should raise ValueError for non-MCPHostStrategy class - with self.assertRaises(ValueError) as context: - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class InvalidStrategy: # Does not inherit from MCPHostStrategy - pass - - self.assertIn("must inherit from MCPHostStrategy", str(context.exception)) - - @regression_test - def test_registry_get_strategy_unknown_host_type(self): - """Test error handling for unknown host type.""" - # Clear registry to ensure no strategies are registered - MCPHostRegistry._strategies.clear() - - with self.assertRaises(ValueError) as context: - MCPHostRegistry.get_strategy(MCPHostType.CLAUDE_DESKTOP) - - self.assertIn("Unknown host type", str(context.exception)) - self.assertIn("Available: []", str(context.exception)) - - @regression_test - def test_registry_singleton_instance_behavior(self): - """Test that registry returns singleton instances.""" - - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class TestStrategy(MCPHostStrategy): - def __init__(self): - self.instance_id = id(self) - - def get_config_path(self): - return Path("/test") - def is_host_available(self): - return True - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - def validate_server_config(self, server_config): - return True - - # Get strategy multiple times - strategy1 = MCPHostRegistry.get_strategy(MCPHostType.CLAUDE_DESKTOP) - strategy2 = MCPHostRegistry.get_strategy(MCPHostType.CLAUDE_DESKTOP) - - # Should be the same instance - self.assertIs(strategy1, strategy2) - self.assertEqual(strategy1.instance_id, strategy2.instance_id) - - @regression_test - def test_registry_detect_available_hosts(self): - """Test host detection functionality.""" - - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class AvailableStrategy(MCPHostStrategy): - def get_config_path(self): - return Path("/test") - def is_host_available(self): - return True # Available - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - def validate_server_config(self, server_config): - return True - - @register_host_strategy(MCPHostType.CURSOR) - class UnavailableStrategy(MCPHostStrategy): - def get_config_path(self): - return Path("/test") - def is_host_available(self): - return False # Not available - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - def validate_server_config(self, server_config): - return True - - @register_host_strategy(MCPHostType.VSCODE) - class ErrorStrategy(MCPHostStrategy): - def get_config_path(self): - return Path("/test") - def is_host_available(self): - raise Exception("Detection error") # Error during detection - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - def validate_server_config(self, server_config): - return True - - available_hosts = MCPHostRegistry.detect_available_hosts() - - # Only the available strategy should be detected - self.assertIn(MCPHostType.CLAUDE_DESKTOP, available_hosts) - self.assertNotIn(MCPHostType.CURSOR, available_hosts) - self.assertNotIn(MCPHostType.VSCODE, available_hosts) - - @regression_test - def test_registry_family_mappings(self): - """Test family host mappings.""" - claude_family = MCPHostRegistry.get_family_hosts("claude") - cursor_family = MCPHostRegistry.get_family_hosts("cursor") - unknown_family = MCPHostRegistry.get_family_hosts("unknown") - - # Verify family mappings - self.assertIn(MCPHostType.CLAUDE_DESKTOP, claude_family) - self.assertIn(MCPHostType.CLAUDE_CODE, claude_family) - self.assertIn(MCPHostType.CURSOR, cursor_family) - self.assertIn(MCPHostType.LMSTUDIO, cursor_family) - self.assertEqual(unknown_family, []) - - @regression_test - def test_registry_get_host_config_path(self): - """Test getting host configuration path through registry.""" - - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class TestStrategy(MCPHostStrategy): - def get_config_path(self): - return Path("/test/claude/config.json") - def is_host_available(self): - return True - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - def validate_server_config(self, server_config): - return True - - config_path = MCPHostRegistry.get_host_config_path(MCPHostType.CLAUDE_DESKTOP) - self.assertEqual(config_path, Path("/test/claude/config.json")) - - -class TestFamilyBasedStrategyRegistration(unittest.TestCase): - """Test suite for family-based strategy registration with decorators.""" - - def setUp(self): - """Set up test environment.""" - # Clear registry before each test - MCPHostRegistry._strategies.clear() - MCPHostRegistry._instances.clear() - - def tearDown(self): - """Clean up test environment.""" - # Clear registry after each test - MCPHostRegistry._strategies.clear() - MCPHostRegistry._instances.clear() - - @regression_test - def test_claude_family_decorator_registration(self): - """Test Claude family strategies register with decorators.""" - - class TestClaudeBase(MCPHostStrategy): - def __init__(self): - self.company_origin = "Anthropic" - self.config_format = "claude_format" - - def validate_server_config(self, server_config): - # Claude family accepts any valid command or URL - if server_config.command or server_config.url: - return True - return False - - @register_host_strategy(MCPHostType.CLAUDE_DESKTOP) - class TestClaudeDesktop(TestClaudeBase): - def get_config_path(self): - return Path("/test/claude_desktop") - def is_host_available(self): - return True - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - - @register_host_strategy(MCPHostType.CLAUDE_CODE) - class TestClaudeCode(TestClaudeBase): - def get_config_path(self): - return Path("/test/claude_code") - def is_host_available(self): - return True - def read_configuration(self): - return HostConfiguration() - def write_configuration(self, config, no_backup=False): - return True - - # Verify both strategies are registered - claude_desktop = MCPHostRegistry.get_strategy(MCPHostType.CLAUDE_DESKTOP) - claude_code = MCPHostRegistry.get_strategy(MCPHostType.CLAUDE_CODE) - - # Verify inheritance properties - self.assertEqual(claude_desktop.company_origin, "Anthropic") - self.assertEqual(claude_code.company_origin, "Anthropic") - self.assertIsInstance(claude_desktop, TestClaudeBase) - self.assertIsInstance(claude_code, TestClaudeBase) - - # Verify family mappings - claude_family = MCPHostRegistry.get_family_hosts("claude") - self.assertIn(MCPHostType.CLAUDE_DESKTOP, claude_family) - self.assertIn(MCPHostType.CLAUDE_CODE, claude_family) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_pydantic_architecture_v4.py b/tests/test_mcp_pydantic_architecture_v4.py deleted file mode 100644 index 4a332d9..0000000 --- a/tests/test_mcp_pydantic_architecture_v4.py +++ /dev/null @@ -1,603 +0,0 @@ -""" -Test suite for Round 04 v4 Pydantic Model Hierarchy. - -This module tests the new model hierarchy including MCPServerConfigBase, -host-specific models (Gemini, VS Code, Cursor, Claude), MCPServerConfigOmni, -HOST_MODEL_REGISTRY, and from_omni() conversion methods. -""" - -import unittest -import sys -from pathlib import Path - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import regression_test -except ImportError: - # Fallback decorator if wobble is not available - def regression_test(func): - return func - -from hatch.mcp_host_config.models import ( - MCPServerConfigBase, - MCPServerConfigGemini, - MCPServerConfigVSCode, - MCPServerConfigCursor, - MCPServerConfigClaude, - MCPServerConfigOmni, - HOST_MODEL_REGISTRY, - MCPHostType -) -from pydantic import ValidationError - - -class TestMCPServerConfigBase(unittest.TestCase): - """Test suite for MCPServerConfigBase model.""" - - @regression_test - def test_base_model_local_server_validation_success(self): - """Test successful local server configuration with type inference.""" - config = MCPServerConfigBase( - name="test-server", - command="python", - args=["server.py"], - env={"API_KEY": "test"} - ) - - self.assertEqual(config.command, "python") - self.assertEqual(config.type, "stdio") # Inferred from command - self.assertEqual(len(config.args), 1) - self.assertEqual(config.env["API_KEY"], "test") - - @regression_test - def test_base_model_remote_server_validation_success(self): - """Test successful remote server configuration with type inference.""" - config = MCPServerConfigBase( - name="test-server", - url="https://api.example.com/mcp", - headers={"Authorization": "Bearer token"} - ) - - self.assertEqual(config.url, "https://api.example.com/mcp") - self.assertEqual(config.type, "sse") # Inferred from url (default to sse) - self.assertEqual(config.headers["Authorization"], "Bearer token") - - @regression_test - def test_base_model_mutual_exclusion_validation_fails(self): - """Test validation fails when both command and url provided.""" - with self.assertRaises(ValidationError) as context: - MCPServerConfigBase( - name="test-server", - command="python", - url="https://api.example.com/mcp" - ) - - self.assertIn("Cannot specify both 'command' and 'url'", str(context.exception)) - - @regression_test - def test_base_model_type_field_stdio_validation(self): - """Test type=stdio validation.""" - # Valid: type=stdio with command - config = MCPServerConfigBase( - name="test-server", - type="stdio", - command="python" - ) - self.assertEqual(config.type, "stdio") - self.assertEqual(config.command, "python") - - # Invalid: type=stdio without command - with self.assertRaises(ValidationError) as context: - MCPServerConfigBase( - name="test-server", - type="stdio", - url="https://api.example.com/mcp" - ) - self.assertIn("'command' is required for stdio transport", str(context.exception)) - - @regression_test - def test_base_model_type_field_sse_validation(self): - """Test type=sse validation.""" - # Valid: type=sse with url - config = MCPServerConfigBase( - name="test-server", - type="sse", - url="https://api.example.com/mcp" - ) - self.assertEqual(config.type, "sse") - self.assertEqual(config.url, "https://api.example.com/mcp") - - # Invalid: type=sse without url - with self.assertRaises(ValidationError) as context: - MCPServerConfigBase( - name="test-server", - type="sse", - command="python" - ) - self.assertIn("'url' is required for sse/http transports", str(context.exception)) - - @regression_test - def test_base_model_type_field_http_validation(self): - """Test type=http validation.""" - # Valid: type=http with url - config = MCPServerConfigBase( - name="test-server", - type="http", - url="https://api.example.com/mcp" - ) - self.assertEqual(config.type, "http") - self.assertEqual(config.url, "https://api.example.com/mcp") - - # Invalid: type=http without url - with self.assertRaises(ValidationError) as context: - MCPServerConfigBase( - name="test-server", - type="http", - command="python" - ) - self.assertIn("'url' is required for sse/http transports", str(context.exception)) - - @regression_test - def test_base_model_type_field_invalid_value(self): - """Test validation fails for invalid type value.""" - with self.assertRaises(ValidationError) as context: - MCPServerConfigBase( - name="test-server", - type="invalid", - command="python" - ) - - # Pydantic will reject invalid Literal value - self.assertIn("Input should be 'stdio', 'sse' or 'http'", str(context.exception)) - - -class TestMCPServerConfigGemini(unittest.TestCase): - """Test suite for MCPServerConfigGemini model.""" - - @regression_test - def test_gemini_model_with_all_fields(self): - """Test Gemini model with all Gemini-specific fields.""" - config = MCPServerConfigGemini( - name="gemini-server", - command="npx", - args=["-y", "server"], - env={"API_KEY": "test"}, - cwd="/path/to/dir", - timeout=30000, - trust=True, - includeTools=["tool1", "tool2"], - excludeTools=["tool3"] - ) - - # Verify universal fields - self.assertEqual(config.command, "npx") - self.assertEqual(config.type, "stdio") # Inferred - - # Verify Gemini-specific fields - self.assertEqual(config.cwd, "/path/to/dir") - self.assertEqual(config.timeout, 30000) - self.assertTrue(config.trust) - self.assertEqual(len(config.includeTools), 2) - self.assertEqual(len(config.excludeTools), 1) - - @regression_test - def test_gemini_model_minimal_configuration(self): - """Test Gemini model with minimal configuration.""" - config = MCPServerConfigGemini( - name="gemini-server", - command="python" - ) - - self.assertEqual(config.command, "python") - self.assertEqual(config.type, "stdio") # Inferred - self.assertIsNone(config.cwd) - self.assertIsNone(config.timeout) - self.assertIsNone(config.trust) - - @regression_test - def test_gemini_model_field_filtering(self): - """Test Gemini model field filtering with model_dump.""" - config = MCPServerConfigGemini( - name="gemini-server", - command="python", - cwd="/path/to/dir" - ) - - # Use model_dump(exclude_unset=True) to get only set fields - data = config.model_dump(exclude_unset=True) - - # Should include name, command, cwd, type (inferred) - self.assertIn("name", data) - self.assertIn("command", data) - self.assertIn("cwd", data) - self.assertIn("type", data) - - # Should NOT include unset fields - self.assertNotIn("timeout", data) - self.assertNotIn("trust", data) - - -class TestMCPServerConfigVSCode(unittest.TestCase): - """Test suite for MCPServerConfigVSCode model.""" - - @regression_test - def test_vscode_model_with_inputs_array(self): - """Test VS Code model with inputs array.""" - config = MCPServerConfigVSCode( - name="vscode-server", - command="python", - args=["server.py"], - inputs=[ - { - "type": "promptString", - "id": "api-key", - "description": "API Key", - "password": True - } - ] - ) - - self.assertEqual(config.command, "python") - self.assertEqual(len(config.inputs), 1) - self.assertEqual(config.inputs[0]["id"], "api-key") - self.assertTrue(config.inputs[0]["password"]) - - @regression_test - def test_vscode_model_with_envFile(self): - """Test VS Code model with envFile field.""" - config = MCPServerConfigVSCode( - name="vscode-server", - command="python", - envFile=".env" - ) - - self.assertEqual(config.command, "python") - self.assertEqual(config.envFile, ".env") - - @regression_test - def test_vscode_model_minimal_configuration(self): - """Test VS Code model with minimal configuration.""" - config = MCPServerConfigVSCode( - name="vscode-server", - command="python" - ) - - self.assertEqual(config.command, "python") - self.assertEqual(config.type, "stdio") # Inferred - self.assertIsNone(config.envFile) - self.assertIsNone(config.inputs) - - -class TestMCPServerConfigCursor(unittest.TestCase): - """Test suite for MCPServerConfigCursor model.""" - - @regression_test - def test_cursor_model_with_envFile(self): - """Test Cursor model with envFile field.""" - config = MCPServerConfigCursor( - name="cursor-server", - command="python", - envFile=".env" - ) - - self.assertEqual(config.command, "python") - self.assertEqual(config.envFile, ".env") - - @regression_test - def test_cursor_model_minimal_configuration(self): - """Test Cursor model with minimal configuration.""" - config = MCPServerConfigCursor( - name="cursor-server", - command="python" - ) - - self.assertEqual(config.command, "python") - self.assertEqual(config.type, "stdio") # Inferred - self.assertIsNone(config.envFile) - - @regression_test - def test_cursor_model_env_with_interpolation_syntax(self): - """Test Cursor model with env containing interpolation syntax.""" - # Our code writes the literal string value - # Cursor handles ${env:NAME}, ${userHome}, etc. expansion at runtime - config = MCPServerConfigCursor( - name="cursor-server", - command="python", - env={"API_KEY": "${env:API_KEY}", "HOME": "${userHome}"} - ) - - self.assertEqual(config.env["API_KEY"], "${env:API_KEY}") - self.assertEqual(config.env["HOME"], "${userHome}") - - -class TestMCPServerConfigClaude(unittest.TestCase): - """Test suite for MCPServerConfigClaude model.""" - - @regression_test - def test_claude_model_universal_fields_only(self): - """Test Claude model with universal fields only.""" - config = MCPServerConfigClaude( - name="claude-server", - command="python", - args=["server.py"], - env={"API_KEY": "test"} - ) - - # Verify universal fields work - self.assertEqual(config.command, "python") - self.assertEqual(config.type, "stdio") # Inferred - self.assertEqual(len(config.args), 1) - self.assertEqual(config.env["API_KEY"], "test") - - @regression_test - def test_claude_model_all_transport_types(self): - """Test Claude model supports all transport types.""" - # stdio transport - config_stdio = MCPServerConfigClaude( - name="claude-server", - type="stdio", - command="python" - ) - self.assertEqual(config_stdio.type, "stdio") - - # sse transport - config_sse = MCPServerConfigClaude( - name="claude-server", - type="sse", - url="https://api.example.com/mcp" - ) - self.assertEqual(config_sse.type, "sse") - - # http transport - config_http = MCPServerConfigClaude( - name="claude-server", - type="http", - url="https://api.example.com/mcp" - ) - self.assertEqual(config_http.type, "http") - - -class TestMCPServerConfigOmni(unittest.TestCase): - """Test suite for MCPServerConfigOmni model.""" - - @regression_test - def test_omni_model_all_fields_optional(self): - """Test Omni model with no fields (all optional).""" - # Should not raise ValidationError - config = MCPServerConfigOmni() - - self.assertIsNone(config.name) - self.assertIsNone(config.command) - self.assertIsNone(config.url) - - @regression_test - def test_omni_model_with_mixed_host_fields(self): - """Test Omni model with fields from multiple hosts.""" - config = MCPServerConfigOmni( - name="omni-server", - command="python", - cwd="/path/to/dir", # Gemini field - envFile=".env" # VS Code/Cursor field - ) - - self.assertEqual(config.command, "python") - self.assertEqual(config.cwd, "/path/to/dir") - self.assertEqual(config.envFile, ".env") - - @regression_test - def test_omni_model_exclude_unset(self): - """Test Omni model with exclude_unset.""" - config = MCPServerConfigOmni( - name="omni-server", - command="python", - args=["server.py"] - ) - - # Use model_dump(exclude_unset=True) - data = config.model_dump(exclude_unset=True) - - # Should only include set fields - self.assertIn("name", data) - self.assertIn("command", data) - self.assertIn("args", data) - - # Should NOT include unset fields - self.assertNotIn("url", data) - self.assertNotIn("cwd", data) - self.assertNotIn("envFile", data) - - -class TestHostModelRegistry(unittest.TestCase): - """Test suite for HOST_MODEL_REGISTRY dictionary dispatch.""" - - @regression_test - def test_registry_contains_all_host_types(self): - """Test registry contains entries for all MCPHostType values.""" - # Verify registry has entries for all host types - self.assertIn(MCPHostType.GEMINI, HOST_MODEL_REGISTRY) - self.assertIn(MCPHostType.CLAUDE_DESKTOP, HOST_MODEL_REGISTRY) - self.assertIn(MCPHostType.CLAUDE_CODE, HOST_MODEL_REGISTRY) - self.assertIn(MCPHostType.VSCODE, HOST_MODEL_REGISTRY) - self.assertIn(MCPHostType.CURSOR, HOST_MODEL_REGISTRY) - self.assertIn(MCPHostType.LMSTUDIO, HOST_MODEL_REGISTRY) - - # Verify correct model classes - self.assertEqual(HOST_MODEL_REGISTRY[MCPHostType.GEMINI], MCPServerConfigGemini) - self.assertEqual(HOST_MODEL_REGISTRY[MCPHostType.CLAUDE_DESKTOP], MCPServerConfigClaude) - self.assertEqual(HOST_MODEL_REGISTRY[MCPHostType.CLAUDE_CODE], MCPServerConfigClaude) - self.assertEqual(HOST_MODEL_REGISTRY[MCPHostType.VSCODE], MCPServerConfigVSCode) - self.assertEqual(HOST_MODEL_REGISTRY[MCPHostType.CURSOR], MCPServerConfigCursor) - self.assertEqual(HOST_MODEL_REGISTRY[MCPHostType.LMSTUDIO], MCPServerConfigCursor) - - @regression_test - def test_registry_dictionary_dispatch(self): - """Test dictionary dispatch retrieves correct model class.""" - # Test Gemini - gemini_class = HOST_MODEL_REGISTRY[MCPHostType.GEMINI] - self.assertEqual(gemini_class, MCPServerConfigGemini) - - # Test VS Code - vscode_class = HOST_MODEL_REGISTRY[MCPHostType.VSCODE] - self.assertEqual(vscode_class, MCPServerConfigVSCode) - - # Test Cursor - cursor_class = HOST_MODEL_REGISTRY[MCPHostType.CURSOR] - self.assertEqual(cursor_class, MCPServerConfigCursor) - - # Test Claude Desktop - claude_class = HOST_MODEL_REGISTRY[MCPHostType.CLAUDE_DESKTOP] - self.assertEqual(claude_class, MCPServerConfigClaude) - - -class TestFromOmniConversion(unittest.TestCase): - """Test suite for from_omni() conversion methods.""" - - @regression_test - def test_gemini_from_omni_with_supported_fields(self): - """Test Gemini from_omni with supported fields.""" - omni = MCPServerConfigOmni( - name="gemini-server", - command="npx", - args=["-y", "server"], - cwd="/path/to/dir", - timeout=30000 - ) - - # Convert to Gemini model - gemini = MCPServerConfigGemini.from_omni(omni) - - # Verify all supported fields transferred - self.assertEqual(gemini.name, "gemini-server") - self.assertEqual(gemini.command, "npx") - self.assertEqual(len(gemini.args), 2) - self.assertEqual(gemini.cwd, "/path/to/dir") - self.assertEqual(gemini.timeout, 30000) - - @regression_test - def test_gemini_from_omni_with_unsupported_fields(self): - """Test Gemini from_omni excludes unsupported fields.""" - omni = MCPServerConfigOmni( - name="gemini-server", - command="python", - cwd="/path/to/dir", # Gemini field - envFile=".env" # VS Code field (unsupported by Gemini) - ) - - # Convert to Gemini model - gemini = MCPServerConfigGemini.from_omni(omni) - - # Verify Gemini fields transferred - self.assertEqual(gemini.command, "python") - self.assertEqual(gemini.cwd, "/path/to/dir") - - # Verify unsupported field NOT transferred - # (Gemini model doesn't have envFile field) - self.assertFalse(hasattr(gemini, 'envFile') and gemini.envFile is not None) - - @regression_test - def test_vscode_from_omni_with_supported_fields(self): - """Test VS Code from_omni with supported fields.""" - omni = MCPServerConfigOmni( - name="vscode-server", - command="python", - args=["server.py"], - envFile=".env", - inputs=[{"type": "promptString", "id": "api-key"}] - ) - - # Convert to VS Code model - vscode = MCPServerConfigVSCode.from_omni(omni) - - # Verify all supported fields transferred - self.assertEqual(vscode.name, "vscode-server") - self.assertEqual(vscode.command, "python") - self.assertEqual(vscode.envFile, ".env") - self.assertEqual(len(vscode.inputs), 1) - - @regression_test - def test_cursor_from_omni_with_supported_fields(self): - """Test Cursor from_omni with supported fields.""" - omni = MCPServerConfigOmni( - name="cursor-server", - command="python", - args=["server.py"], - envFile=".env" - ) - - # Convert to Cursor model - cursor = MCPServerConfigCursor.from_omni(omni) - - # Verify all supported fields transferred - self.assertEqual(cursor.name, "cursor-server") - self.assertEqual(cursor.command, "python") - self.assertEqual(cursor.envFile, ".env") - - @regression_test - def test_claude_from_omni_with_universal_fields(self): - """Test Claude from_omni with universal fields only.""" - omni = MCPServerConfigOmni( - name="claude-server", - command="python", - args=["server.py"], - env={"API_KEY": "test"}, - type="stdio" - ) - - # Convert to Claude model - claude = MCPServerConfigClaude.from_omni(omni) - - # Verify universal fields transferred - self.assertEqual(claude.name, "claude-server") - self.assertEqual(claude.command, "python") - self.assertEqual(claude.type, "stdio") - self.assertEqual(len(claude.args), 1) - self.assertEqual(claude.env["API_KEY"], "test") - - -class TestGeminiDualTransport(unittest.TestCase): - """Test suite for Gemini dual-transport validation (Issue 3).""" - - @regression_test - def test_gemini_sse_transport_with_url(self): - """Test Gemini SSE transport uses url field.""" - config = MCPServerConfigGemini( - name="gemini-server", - type="sse", - url="https://api.example.com/mcp" - ) - - self.assertEqual(config.type, "sse") - self.assertEqual(config.url, "https://api.example.com/mcp") - self.assertIsNone(config.httpUrl) - - @regression_test - def test_gemini_http_transport_with_httpUrl(self): - """Test Gemini HTTP transport uses httpUrl field.""" - config = MCPServerConfigGemini( - name="gemini-server", - type="http", - httpUrl="https://api.example.com/mcp" - ) - - self.assertEqual(config.type, "http") - self.assertEqual(config.httpUrl, "https://api.example.com/mcp") - self.assertIsNone(config.url) - - @regression_test - def test_gemini_mutual_exclusion_url_and_httpUrl(self): - """Test Gemini rejects both url and httpUrl simultaneously.""" - with self.assertRaises(ValidationError) as context: - MCPServerConfigGemini( - name="gemini-server", - url="https://api.example.com/sse", - httpUrl="https://api.example.com/http" - ) - - self.assertIn("Cannot specify both 'url' and 'httpUrl'", str(context.exception)) - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/test_mcp_server_config_models.py b/tests/test_mcp_server_config_models.py deleted file mode 100644 index 92d3348..0000000 --- a/tests/test_mcp_server_config_models.py +++ /dev/null @@ -1,242 +0,0 @@ -""" -Test suite for consolidated MCPServerConfig Pydantic model. - -This module tests the consolidated MCPServerConfig model that supports -both local and remote server configurations with proper validation. -""" - -import unittest -import sys -from pathlib import Path - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import regression_test, integration_test -except ImportError: - # Fallback decorators if wobble is not available - def regression_test(func): - return func - - def integration_test(scope="component"): - def decorator(func): - return func - return decorator - -from test_data_utils import MCPHostConfigTestDataLoader -from hatch.mcp_host_config.models import MCPServerConfig -from pydantic import ValidationError - - -class TestMCPServerConfigModels(unittest.TestCase): - """Test suite for consolidated MCPServerConfig Pydantic model.""" - - def setUp(self): - """Set up test environment.""" - self.test_data_loader = MCPHostConfigTestDataLoader() - - @regression_test - def test_mcp_server_config_local_server_validation_success(self): - """Test successful local server configuration validation.""" - config_data = self.test_data_loader.load_mcp_server_config("local") - config = MCPServerConfig(**config_data) - - self.assertEqual(config.command, "python") - self.assertEqual(len(config.args), 3) - self.assertEqual(config.env["API_KEY"], "test") - self.assertTrue(config.is_local_server) - self.assertFalse(config.is_remote_server) - - @regression_test - def test_mcp_server_config_remote_server_validation_success(self): - """Test successful remote server configuration validation.""" - config_data = self.test_data_loader.load_mcp_server_config("remote") - config = MCPServerConfig(**config_data) - - self.assertEqual(config.url, "https://api.example.com/mcp") - self.assertEqual(config.headers["Authorization"], "Bearer token") - self.assertFalse(config.is_local_server) - self.assertTrue(config.is_remote_server) - - @regression_test - def test_mcp_server_config_validation_fails_both_command_and_url(self): - """Test validation fails when both command and URL are provided.""" - config_data = { - "command": "python", - "args": ["server.py"], - "url": "https://example.com/mcp" # Invalid: both command and URL - } - - with self.assertRaises(ValidationError) as context: - MCPServerConfig(**config_data) - - self.assertIn("Cannot specify both 'command' and 'url'", str(context.exception)) - - @regression_test - def test_mcp_server_config_validation_fails_neither_command_nor_url(self): - """Test validation fails when neither command nor URL are provided.""" - config_data = { - "env": {"TEST": "value"} - # Missing both command and url - } - - with self.assertRaises(ValidationError) as context: - MCPServerConfig(**config_data) - - self.assertIn("Either 'command' (local server) or 'url' (remote server) must be provided", - str(context.exception)) - - @regression_test - def test_mcp_server_config_validation_args_without_command_fails(self): - """Test validation fails when args provided without command.""" - config_data = { - "url": "https://example.com/mcp", - "args": ["--flag"] # Invalid: args without command - } - - with self.assertRaises(ValidationError) as context: - MCPServerConfig(**config_data) - - self.assertIn("'args' can only be specified with 'command'", str(context.exception)) - - @regression_test - def test_mcp_server_config_validation_headers_without_url_fails(self): - """Test validation fails when headers provided without URL.""" - config_data = { - "command": "python", - "headers": {"Authorization": "Bearer token"} # Invalid: headers without URL - } - - with self.assertRaises(ValidationError) as context: - MCPServerConfig(**config_data) - - self.assertIn("'headers' can only be specified with 'url'", str(context.exception)) - - @regression_test - def test_mcp_server_config_url_format_validation(self): - """Test URL format validation.""" - invalid_urls = ["ftp://example.com", "example.com", "not-a-url"] - - for invalid_url in invalid_urls: - with self.assertRaises(ValidationError): - MCPServerConfig(url=invalid_url) - - @regression_test - def test_mcp_server_config_no_future_extension_fields(self): - """Test that extra fields are allowed for host-specific extensions.""" - # Current design allows extra fields to support host-specific configurations - # (e.g., Gemini's timeout, VS Code's envFile, etc.) - config_data = { - "command": "python", - "timeout": 30, # Allowed (host-specific field) - "retry_attempts": 3, # Allowed (host-specific field) - "ssl_verify": True # Allowed (host-specific field) - } - - # Should NOT raise ValidationError (extra="allow") - config = MCPServerConfig(**config_data) - - # Verify core fields are set correctly - self.assertEqual(config.command, "python") - - # Note: In Phase 3B, strict validation will be enforced in host-specific models - - @regression_test - def test_mcp_server_config_command_empty_validation(self): - """Test validation fails for empty command.""" - config_data = { - "command": " ", # Empty/whitespace command - "args": ["server.py"] - } - - with self.assertRaises(ValidationError) as context: - MCPServerConfig(**config_data) - - self.assertIn("Command cannot be empty", str(context.exception)) - - @regression_test - def test_mcp_server_config_command_strip_whitespace(self): - """Test command whitespace is stripped.""" - config_data = { - "command": " python ", - "args": ["server.py"] - } - - config = MCPServerConfig(**config_data) - self.assertEqual(config.command, "python") - - @regression_test - def test_mcp_server_config_minimal_local_server(self): - """Test minimal local server configuration.""" - config_data = self.test_data_loader.load_mcp_server_config("local_minimal") - config = MCPServerConfig(**config_data) - - self.assertEqual(config.command, "python") - self.assertEqual(config.args, ["minimal_server.py"]) - self.assertIsNone(config.env) - self.assertTrue(config.is_local_server) - self.assertFalse(config.is_remote_server) - - @regression_test - def test_mcp_server_config_minimal_remote_server(self): - """Test minimal remote server configuration.""" - config_data = self.test_data_loader.load_mcp_server_config("remote_minimal") - config = MCPServerConfig(**config_data) - - self.assertEqual(config.url, "https://minimal.example.com/mcp") - self.assertIsNone(config.headers) - self.assertFalse(config.is_local_server) - self.assertTrue(config.is_remote_server) - - @regression_test - def test_mcp_server_config_serialization_roundtrip(self): - """Test serialization and deserialization roundtrip.""" - # Test local server - local_config_data = self.test_data_loader.load_mcp_server_config("local") - local_config = MCPServerConfig(**local_config_data) - - # Serialize and deserialize - serialized = local_config.model_dump() - roundtrip_config = MCPServerConfig(**serialized) - - self.assertEqual(local_config.command, roundtrip_config.command) - self.assertEqual(local_config.args, roundtrip_config.args) - self.assertEqual(local_config.env, roundtrip_config.env) - self.assertEqual(local_config.is_local_server, roundtrip_config.is_local_server) - - # Test remote server - remote_config_data = self.test_data_loader.load_mcp_server_config("remote") - remote_config = MCPServerConfig(**remote_config_data) - - # Serialize and deserialize - serialized = remote_config.model_dump() - roundtrip_config = MCPServerConfig(**serialized) - - self.assertEqual(remote_config.url, roundtrip_config.url) - self.assertEqual(remote_config.headers, roundtrip_config.headers) - self.assertEqual(remote_config.is_remote_server, roundtrip_config.is_remote_server) - - @regression_test - def test_mcp_server_config_json_serialization(self): - """Test JSON serialization compatibility.""" - import json - - config_data = self.test_data_loader.load_mcp_server_config("local") - config = MCPServerConfig(**config_data) - - # Test JSON serialization - json_str = config.model_dump_json() - self.assertIsInstance(json_str, str) - - # Test JSON deserialization - parsed_data = json.loads(json_str) - roundtrip_config = MCPServerConfig(**parsed_data) - - self.assertEqual(config.command, roundtrip_config.command) - self.assertEqual(config.args, roundtrip_config.args) - self.assertEqual(config.env, roundtrip_config.env) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_server_config_type_field.py b/tests/test_mcp_server_config_type_field.py deleted file mode 100644 index 733eeb8..0000000 --- a/tests/test_mcp_server_config_type_field.py +++ /dev/null @@ -1,221 +0,0 @@ -""" -Test suite for MCPServerConfig type field (Phase 3A). - -This module tests the type field addition to MCPServerConfig model, -including validation and property behavior. -""" - -import unittest -import sys -from pathlib import Path - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import regression_test -except ImportError: - # Fallback decorator if wobble is not available - def regression_test(func): - return func - -from hatch.mcp_host_config.models import MCPServerConfig -from pydantic import ValidationError - - -class TestMCPServerConfigTypeField(unittest.TestCase): - """Test suite for MCPServerConfig type field validation.""" - - @regression_test - def test_type_stdio_with_command_success(self): - """Test successful stdio type with command.""" - config = MCPServerConfig( - name="test-server", - type="stdio", - command="python", - args=["server.py"] - ) - - self.assertEqual(config.type, "stdio") - self.assertEqual(config.command, "python") - self.assertTrue(config.is_local_server) - self.assertFalse(config.is_remote_server) - - @regression_test - def test_type_sse_with_url_success(self): - """Test successful sse type with url.""" - config = MCPServerConfig( - name="test-server", - type="sse", - url="https://api.example.com/mcp" - ) - - self.assertEqual(config.type, "sse") - self.assertEqual(config.url, "https://api.example.com/mcp") - self.assertFalse(config.is_local_server) - self.assertTrue(config.is_remote_server) - - @regression_test - def test_type_http_with_url_success(self): - """Test successful http type with url.""" - config = MCPServerConfig( - name="test-server", - type="http", - url="https://api.example.com/mcp", - headers={"Authorization": "Bearer token"} - ) - - self.assertEqual(config.type, "http") - self.assertEqual(config.url, "https://api.example.com/mcp") - self.assertFalse(config.is_local_server) - self.assertTrue(config.is_remote_server) - - @regression_test - def test_type_stdio_without_command_fails(self): - """Test validation fails when type=stdio without command.""" - with self.assertRaises(ValidationError) as context: - MCPServerConfig( - name="test-server", - type="stdio", - url="https://api.example.com/mcp" # Invalid: stdio with url - ) - - self.assertIn("'type=stdio' requires 'command' field", str(context.exception)) - - @regression_test - def test_type_stdio_with_url_fails(self): - """Test validation fails when type=stdio with url.""" - with self.assertRaises(ValidationError) as context: - MCPServerConfig( - name="test-server", - type="stdio", - command="python", - url="https://api.example.com/mcp" # Invalid: both command and url - ) - - # The validate_server_type() validator catches this first - self.assertIn("Cannot specify both 'command' and 'url'", str(context.exception)) - - @regression_test - def test_type_sse_without_url_fails(self): - """Test validation fails when type=sse without url.""" - with self.assertRaises(ValidationError) as context: - MCPServerConfig( - name="test-server", - type="sse", - command="python" # Invalid: sse with command - ) - - self.assertIn("'type=sse' requires 'url' field", str(context.exception)) - - @regression_test - def test_type_http_without_url_fails(self): - """Test validation fails when type=http without url.""" - with self.assertRaises(ValidationError) as context: - MCPServerConfig( - name="test-server", - type="http", - command="python" # Invalid: http with command - ) - - self.assertIn("'type=http' requires 'url' field", str(context.exception)) - - @regression_test - def test_type_sse_with_command_fails(self): - """Test validation fails when type=sse with command.""" - with self.assertRaises(ValidationError) as context: - MCPServerConfig( - name="test-server", - type="sse", - command="python", - url="https://api.example.com/mcp" # Invalid: both command and url - ) - - # The validate_server_type() validator catches this first - self.assertIn("Cannot specify both 'command' and 'url'", str(context.exception)) - - @regression_test - def test_backward_compatibility_no_type_field_local(self): - """Test backward compatibility: local server without type field.""" - config = MCPServerConfig( - name="test-server", - command="python", - args=["server.py"] - ) - - self.assertIsNone(config.type) - self.assertEqual(config.command, "python") - self.assertTrue(config.is_local_server) - self.assertFalse(config.is_remote_server) - - @regression_test - def test_backward_compatibility_no_type_field_remote(self): - """Test backward compatibility: remote server without type field.""" - config = MCPServerConfig( - name="test-server", - url="https://api.example.com/mcp" - ) - - self.assertIsNone(config.type) - self.assertEqual(config.url, "https://api.example.com/mcp") - self.assertFalse(config.is_local_server) - self.assertTrue(config.is_remote_server) - - @regression_test - def test_type_field_with_env_variables(self): - """Test type field with environment variables.""" - config = MCPServerConfig( - name="test-server", - type="stdio", - command="python", - args=["server.py"], - env={"API_KEY": "test-key", "DEBUG": "true"} - ) - - self.assertEqual(config.type, "stdio") - self.assertEqual(config.env["API_KEY"], "test-key") - self.assertEqual(config.env["DEBUG"], "true") - - @regression_test - def test_type_field_serialization(self): - """Test type field is included in serialization.""" - config = MCPServerConfig( - name="test-server", - type="stdio", - command="python", - args=["server.py"] - ) - - # Test model_dump includes type field - data = config.model_dump() - self.assertEqual(data["type"], "stdio") - self.assertEqual(data["command"], "python") - - # Test JSON serialization - import json - json_str = config.model_dump_json() - parsed = json.loads(json_str) - self.assertEqual(parsed["type"], "stdio") - - @regression_test - def test_type_field_roundtrip(self): - """Test type field survives serialization roundtrip.""" - original = MCPServerConfig( - name="test-server", - type="sse", - url="https://api.example.com/mcp", - headers={"Authorization": "Bearer token"} - ) - - # Serialize and deserialize - data = original.model_dump() - roundtrip = MCPServerConfig(**data) - - self.assertEqual(roundtrip.type, "sse") - self.assertEqual(roundtrip.url, "https://api.example.com/mcp") - self.assertEqual(roundtrip.headers["Authorization"], "Bearer token") - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/test_mcp_sync_functionality.py b/tests/test_mcp_sync_functionality.py deleted file mode 100644 index 0cd5b20..0000000 --- a/tests/test_mcp_sync_functionality.py +++ /dev/null @@ -1,316 +0,0 @@ -""" -Test suite for MCP synchronization functionality (Phase 3f). - -This module contains comprehensive tests for the advanced synchronization -features including cross-environment and cross-host synchronization. -""" - -import unittest -from unittest.mock import MagicMock, patch, call -from pathlib import Path -import tempfile -import json -from typing import Dict, List, Optional - -# Import test decorators from wobble framework -from wobble import integration_test, regression_test - -# Import the modules we'll be testing -from hatch.mcp_host_config.host_management import MCPHostConfigurationManager, MCPHostType -from hatch.mcp_host_config.models import ( - EnvironmentData, MCPServerConfig, SyncResult, ConfigurationResult -) -from hatch.cli_hatch import handle_mcp_sync, parse_host_list, main - - -class TestMCPSyncConfigurations(unittest.TestCase): - """Test suite for MCPHostConfigurationManager.sync_configurations() method.""" - - def setUp(self): - """Set up test fixtures.""" - self.temp_dir = tempfile.mkdtemp() - self.manager = MCPHostConfigurationManager() - - # We'll use mocks instead of real data objects to avoid validation issues - - @regression_test - def test_sync_from_environment_to_single_host(self): - """Test basic environment-to-host synchronization.""" - with patch.object(self.manager, 'sync_configurations') as mock_sync: - mock_result = SyncResult( - success=True, - results=[ConfigurationResult(success=True, hostname="claude-desktop")], - servers_synced=2, - hosts_updated=1 - ) - mock_sync.return_value = mock_result - - result = self.manager.sync_configurations( - from_env="test-env", - to_hosts=["claude-desktop"] - ) - - self.assertTrue(result.success) - self.assertEqual(result.servers_synced, 2) - self.assertEqual(result.hosts_updated, 1) - mock_sync.assert_called_once() - - @integration_test(scope="component") - def test_sync_from_environment_to_multiple_hosts(self): - """Test environment-to-multiple-hosts synchronization.""" - with patch.object(self.manager, 'sync_configurations') as mock_sync: - mock_result = SyncResult( - success=True, - results=[ - ConfigurationResult(success=True, hostname="claude-desktop"), - ConfigurationResult(success=True, hostname="cursor") - ], - servers_synced=4, - hosts_updated=2 - ) - mock_sync.return_value = mock_result - - result = self.manager.sync_configurations( - from_env="test-env", - to_hosts=["claude-desktop", "cursor"] - ) - - self.assertTrue(result.success) - self.assertEqual(result.servers_synced, 4) - self.assertEqual(result.hosts_updated, 2) - - @integration_test(scope="component") - def test_sync_from_host_to_host(self): - """Test host-to-host configuration synchronization.""" - # This test will validate the new host-to-host sync functionality - # that needs to be implemented - with patch.object(self.manager.host_registry, 'get_strategy') as mock_get_strategy: - mock_strategy = MagicMock() - mock_strategy.read_configuration.return_value = MagicMock() - mock_strategy.write_configuration.return_value = True - mock_get_strategy.return_value = mock_strategy - - # Mock the sync_configurations method that we'll implement - with patch.object(self.manager, 'sync_configurations') as mock_sync: - mock_result = SyncResult( - success=True, - results=[ConfigurationResult(success=True, hostname="cursor")], - servers_synced=2, - hosts_updated=1 - ) - mock_sync.return_value = mock_result - - result = self.manager.sync_configurations( - from_host="claude-desktop", - to_hosts=["cursor"] - ) - - self.assertTrue(result.success) - self.assertEqual(result.hosts_updated, 1) - - @integration_test(scope="component") - def test_sync_with_server_name_filter(self): - """Test synchronization with specific server names.""" - with patch.object(self.manager, 'sync_configurations') as mock_sync: - mock_result = SyncResult( - success=True, - results=[ConfigurationResult(success=True, hostname="claude-desktop")], - servers_synced=1, # Only one server due to filtering - hosts_updated=1 - ) - mock_sync.return_value = mock_result - - result = self.manager.sync_configurations( - from_env="test-env", - to_hosts=["claude-desktop"], - servers=["weather-toolkit"] - ) - - self.assertTrue(result.success) - self.assertEqual(result.servers_synced, 1) - - @integration_test(scope="component") - def test_sync_with_pattern_filter(self): - """Test synchronization with regex pattern filter.""" - with patch.object(self.manager, 'sync_configurations') as mock_sync: - mock_result = SyncResult( - success=True, - results=[ConfigurationResult(success=True, hostname="claude-desktop")], - servers_synced=1, # Only servers matching pattern - hosts_updated=1 - ) - mock_sync.return_value = mock_result - - result = self.manager.sync_configurations( - from_env="test-env", - to_hosts=["claude-desktop"], - pattern="weather-.*" - ) - - self.assertTrue(result.success) - self.assertEqual(result.servers_synced, 1) - - @regression_test - def test_sync_invalid_source_environment(self): - """Test synchronization with non-existent source environment.""" - with patch.object(self.manager, 'sync_configurations') as mock_sync: - mock_result = SyncResult( - success=False, - results=[ConfigurationResult( - success=False, - hostname="claude-desktop", - error_message="Environment 'nonexistent' not found" - )], - servers_synced=0, - hosts_updated=0 - ) - mock_sync.return_value = mock_result - - result = self.manager.sync_configurations( - from_env="nonexistent", - to_hosts=["claude-desktop"] - ) - - self.assertFalse(result.success) - self.assertEqual(result.servers_synced, 0) - - @regression_test - def test_sync_no_source_specified(self): - """Test synchronization without source specification.""" - with self.assertRaises(ValueError) as context: - self.manager.sync_configurations(to_hosts=["claude-desktop"]) - - self.assertIn("Must specify either from_env or from_host", str(context.exception)) - - @regression_test - def test_sync_both_sources_specified(self): - """Test synchronization with both env and host sources.""" - with self.assertRaises(ValueError) as context: - self.manager.sync_configurations( - from_env="test-env", - from_host="claude-desktop", - to_hosts=["cursor"] - ) - - self.assertIn("Cannot specify both from_env and from_host", str(context.exception)) - - -class TestMCPSyncCommandParsing(unittest.TestCase): - """Test suite for MCP sync command argument parsing.""" - - @regression_test - def test_sync_command_basic_parsing(self): - """Test basic sync command argument parsing.""" - test_args = [ - 'hatch', 'mcp', 'sync', - '--from-env', 'test-env', - '--to-host', 'claude-desktop' - ] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_sync', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with( - from_env='test-env', - from_host=None, - to_hosts='claude-desktop', - servers=None, - pattern=None, - dry_run=False, - auto_approve=False, - no_backup=False - ) - except SystemExit as e: - self.assertEqual(e.code, 0) - - @regression_test - def test_sync_command_with_filters(self): - """Test sync command with server filters.""" - test_args = [ - 'hatch', 'mcp', 'sync', - '--from-env', 'test-env', - '--to-host', 'claude-desktop,cursor', - '--servers', 'weather-api,file-manager', - '--dry-run' - ] - - with patch('sys.argv', test_args): - with patch('hatch.cli_hatch.HatchEnvironmentManager'): - with patch('hatch.cli_hatch.handle_mcp_sync', return_value=0) as mock_handler: - try: - main() - mock_handler.assert_called_once_with( - from_env='test-env', - from_host=None, - to_hosts='claude-desktop,cursor', - servers='weather-api,file-manager', - pattern=None, - dry_run=True, - auto_approve=False, - no_backup=False - ) - except SystemExit as e: - self.assertEqual(e.code, 0) - - -class TestMCPSyncCommandHandler(unittest.TestCase): - """Test suite for MCP sync command handler.""" - - @integration_test(scope="component") - def test_handle_sync_environment_to_host(self): - """Test sync handler for environment-to-host operation.""" - with patch('hatch.cli_hatch.MCPHostConfigurationManager') as mock_manager_class: - mock_manager = MagicMock() - mock_result = SyncResult( - success=True, - results=[ConfigurationResult(success=True, hostname="claude-desktop")], - servers_synced=2, - hosts_updated=1 - ) - mock_manager.sync_configurations.return_value = mock_result - mock_manager_class.return_value = mock_manager - - with patch('builtins.print') as mock_print: - with patch('hatch.cli_hatch.parse_host_list') as mock_parse: - with patch('hatch.cli_hatch.request_confirmation', return_value=True) as mock_confirm: - from hatch.mcp_host_config.models import MCPHostType - mock_parse.return_value = [MCPHostType.CLAUDE_DESKTOP] - - result = handle_mcp_sync( - from_env="test-env", - to_hosts="claude-desktop" - ) - - self.assertEqual(result, 0) - mock_manager.sync_configurations.assert_called_once() - mock_confirm.assert_called_once() - - # Verify success output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[SUCCESS] Synchronization completed" in call for call in print_calls)) - - @integration_test(scope="component") - def test_handle_sync_dry_run(self): - """Test sync handler dry-run functionality.""" - with patch('builtins.print') as mock_print: - with patch('hatch.cli_hatch.parse_host_list') as mock_parse: - from hatch.mcp_host_config.models import MCPHostType - mock_parse.return_value = [MCPHostType.CLAUDE_DESKTOP] - - result = handle_mcp_sync( - from_env="test-env", - to_hosts="claude-desktop", - dry_run=True - ) - - self.assertEqual(result, 0) - - # Verify dry-run output - print_calls = [call[0][0] for call in mock_print.call_args_list] - self.assertTrue(any("[DRY RUN] Would synchronize" in call for call in print_calls)) - - -if __name__ == '__main__': - unittest.main() diff --git a/tests/test_mcp_user_feedback_reporting.py b/tests/test_mcp_user_feedback_reporting.py deleted file mode 100644 index 6beff73..0000000 --- a/tests/test_mcp_user_feedback_reporting.py +++ /dev/null @@ -1,359 +0,0 @@ -""" -Test suite for MCP user feedback reporting system. - -This module tests the FieldOperation and ConversionReport models, -generate_conversion_report() function, and display_report() function. -""" - -import unittest -import sys -from pathlib import Path -from io import StringIO - -# Add the parent directory to the path to import wobble -sys.path.insert(0, str(Path(__file__).parent.parent)) - -try: - from wobble.decorators import regression_test -except ImportError: - # Fallback decorator if wobble is not available - def regression_test(func): - return func - -from hatch.mcp_host_config.reporting import ( - FieldOperation, - ConversionReport, - generate_conversion_report, - display_report -) -from hatch.mcp_host_config.models import ( - MCPServerConfigOmni, - MCPHostType -) - - -class TestFieldOperation(unittest.TestCase): - """Test suite for FieldOperation model.""" - - @regression_test - def test_field_operation_updated_str_representation(self): - """Test UPDATED operation string representation.""" - field_op = FieldOperation( - field_name="command", - operation="UPDATED", - old_value="old_command", - new_value="new_command" - ) - - result = str(field_op) - - # Verify ASCII arrow used (not Unicode) - self.assertIn("-->", result) - self.assertNotIn("β†’", result) - - # Verify format - self.assertEqual(result, "command: UPDATED 'old_command' --> 'new_command'") - - @regression_test - def test_field_operation_updated_with_none_old_value(self): - """Test UPDATED operation with None old_value (field added).""" - field_op = FieldOperation( - field_name="timeout", - operation="UPDATED", - old_value=None, - new_value=30000 - ) - - result = str(field_op) - - # Verify None is displayed - self.assertEqual(result, "timeout: UPDATED None --> 30000") - - @regression_test - def test_field_operation_unsupported_str_representation(self): - """Test UNSUPPORTED operation string representation.""" - field_op = FieldOperation( - field_name="envFile", - operation="UNSUPPORTED", - new_value=".env" - ) - - result = str(field_op) - - # Verify format - self.assertEqual(result, "envFile: UNSUPPORTED") - - @regression_test - def test_field_operation_unchanged_str_representation(self): - """Test UNCHANGED operation string representation.""" - field_op = FieldOperation( - field_name="name", - operation="UNCHANGED", - new_value="my-server" - ) - - result = str(field_op) - - # Verify format - self.assertEqual(result, "name: UNCHANGED 'my-server'") - - -class TestConversionReport(unittest.TestCase): - """Test suite for ConversionReport model.""" - - @regression_test - def test_conversion_report_create_operation(self): - """Test ConversionReport with create operation.""" - report = ConversionReport( - operation="create", - server_name="my-server", - target_host=MCPHostType.GEMINI, - field_operations=[ - FieldOperation(field_name="command", operation="UPDATED", old_value=None, new_value="python") - ] - ) - - self.assertEqual(report.operation, "create") - self.assertEqual(report.server_name, "my-server") - self.assertEqual(report.target_host, MCPHostType.GEMINI) - self.assertTrue(report.success) - self.assertIsNone(report.error_message) - self.assertEqual(len(report.field_operations), 1) - self.assertFalse(report.dry_run) - - @regression_test - def test_conversion_report_update_operation(self): - """Test ConversionReport with update operation.""" - report = ConversionReport( - operation="update", - server_name="my-server", - target_host=MCPHostType.VSCODE, - field_operations=[ - FieldOperation(field_name="command", operation="UPDATED", old_value="old", new_value="new"), - FieldOperation(field_name="name", operation="UNCHANGED", new_value="my-server") - ] - ) - - self.assertEqual(report.operation, "update") - self.assertEqual(len(report.field_operations), 2) - - @regression_test - def test_conversion_report_migrate_operation(self): - """Test ConversionReport with migrate operation.""" - report = ConversionReport( - operation="migrate", - server_name="my-server", - source_host=MCPHostType.GEMINI, - target_host=MCPHostType.VSCODE, - field_operations=[] - ) - - self.assertEqual(report.operation, "migrate") - self.assertEqual(report.source_host, MCPHostType.GEMINI) - self.assertEqual(report.target_host, MCPHostType.VSCODE) - - -class TestGenerateConversionReport(unittest.TestCase): - """Test suite for generate_conversion_report() function.""" - - @regression_test - def test_generate_report_create_operation_all_supported(self): - """Test generate_conversion_report for create with all supported fields.""" - omni = MCPServerConfigOmni( - name="gemini-server", - command="npx", - args=["-y", "server"], - cwd="/path/to/dir", - timeout=30000 - ) - - report = generate_conversion_report( - operation="create", - server_name="gemini-server", - target_host=MCPHostType.GEMINI, - omni=omni - ) - - # Verify all fields are UPDATED (create operation) - self.assertEqual(report.operation, "create") - self.assertEqual(report.server_name, "gemini-server") - self.assertEqual(report.target_host, MCPHostType.GEMINI) - - # All set fields should be UPDATED - updated_ops = [op for op in report.field_operations if op.operation == "UPDATED"] - self.assertEqual(len(updated_ops), 5) # name, command, args, cwd, timeout - - # No unsupported fields - unsupported_ops = [op for op in report.field_operations if op.operation == "UNSUPPORTED"] - self.assertEqual(len(unsupported_ops), 0) - - @regression_test - def test_generate_report_create_operation_with_unsupported(self): - """Test generate_conversion_report with unsupported fields.""" - omni = MCPServerConfigOmni( - name="gemini-server", - command="python", - cwd="/path/to/dir", # Gemini field - envFile=".env" # VS Code field (unsupported by Gemini) - ) - - report = generate_conversion_report( - operation="create", - server_name="gemini-server", - target_host=MCPHostType.GEMINI, - omni=omni - ) - - # Verify Gemini fields are UPDATED - updated_ops = [op for op in report.field_operations if op.operation == "UPDATED"] - updated_fields = {op.field_name for op in updated_ops} - self.assertIn("name", updated_fields) - self.assertIn("command", updated_fields) - self.assertIn("cwd", updated_fields) - - # Verify VS Code field is UNSUPPORTED - unsupported_ops = [op for op in report.field_operations if op.operation == "UNSUPPORTED"] - self.assertEqual(len(unsupported_ops), 1) - self.assertEqual(unsupported_ops[0].field_name, "envFile") - - @regression_test - def test_generate_report_update_operation(self): - """Test generate_conversion_report for update operation.""" - old_config = MCPServerConfigOmni( - name="my-server", - command="python", - args=["old.py"] - ) - - new_omni = MCPServerConfigOmni( - name="my-server", - command="python", - args=["new.py"] - ) - - report = generate_conversion_report( - operation="update", - server_name="my-server", - target_host=MCPHostType.GEMINI, - omni=new_omni, - old_config=old_config - ) - - # Verify name and command are UNCHANGED - unchanged_ops = [op for op in report.field_operations if op.operation == "UNCHANGED"] - unchanged_fields = {op.field_name for op in unchanged_ops} - self.assertIn("name", unchanged_fields) - self.assertIn("command", unchanged_fields) - - # Verify args is UPDATED - updated_ops = [op for op in report.field_operations if op.operation == "UPDATED"] - self.assertEqual(len(updated_ops), 1) - self.assertEqual(updated_ops[0].field_name, "args") - self.assertEqual(updated_ops[0].old_value, ["old.py"]) - self.assertEqual(updated_ops[0].new_value, ["new.py"]) - - @regression_test - def test_generate_report_dynamic_field_derivation(self): - """Test that generate_conversion_report uses dynamic field derivation.""" - omni = MCPServerConfigOmni( - name="test-server", - command="python" - ) - - # Generate report for Gemini - report_gemini = generate_conversion_report( - operation="create", - server_name="test-server", - target_host=MCPHostType.GEMINI, - omni=omni - ) - - # All fields should be UPDATED (no unsupported) - unsupported_ops = [op for op in report_gemini.field_operations if op.operation == "UNSUPPORTED"] - self.assertEqual(len(unsupported_ops), 0) - - -class TestDisplayReport(unittest.TestCase): - """Test suite for display_report() function.""" - - @regression_test - def test_display_report_create_operation(self): - """Test display_report for create operation.""" - report = ConversionReport( - operation="create", - server_name="my-server", - target_host=MCPHostType.GEMINI, - field_operations=[ - FieldOperation(field_name="command", operation="UPDATED", old_value=None, new_value="python") - ] - ) - - # Capture stdout - captured_output = StringIO() - sys.stdout = captured_output - - display_report(report) - - sys.stdout = sys.__stdout__ - output = captured_output.getvalue() - - # Verify header - self.assertIn("Server 'my-server' created for host", output) - self.assertIn("gemini", output.lower()) - - # Verify field operation displayed - self.assertIn("command: UPDATED", output) - - @regression_test - def test_display_report_update_operation(self): - """Test display_report for update operation.""" - report = ConversionReport( - operation="update", - server_name="my-server", - target_host=MCPHostType.VSCODE, - field_operations=[ - FieldOperation(field_name="args", operation="UPDATED", old_value=["old.py"], new_value=["new.py"]) - ] - ) - - # Capture stdout - captured_output = StringIO() - sys.stdout = captured_output - - display_report(report) - - sys.stdout = sys.__stdout__ - output = captured_output.getvalue() - - # Verify header - self.assertIn("Server 'my-server' updated for host", output) - - @regression_test - def test_display_report_dry_run(self): - """Test display_report for dry-run mode.""" - report = ConversionReport( - operation="create", - server_name="my-server", - target_host=MCPHostType.GEMINI, - field_operations=[], - dry_run=True - ) - - # Capture stdout - captured_output = StringIO() - sys.stdout = captured_output - - display_report(report) - - sys.stdout = sys.__stdout__ - output = captured_output.getvalue() - - # Verify dry-run header and footer - self.assertIn("[DRY RUN]", output) - self.assertIn("Preview of changes", output) - self.assertIn("No changes were made", output) - - -if __name__ == '__main__': - unittest.main() - diff --git a/tests/test_non_tty_integration.py b/tests/test_non_tty_integration.py index 962936a..d28eb8c 100644 --- a/tests/test_non_tty_integration.py +++ b/tests/test_non_tty_integration.py @@ -11,151 +11,144 @@ from pathlib import Path from unittest.mock import patch from hatch.environment_manager import HatchEnvironmentManager -from wobble.decorators import integration_test, slow_test +from wobble.decorators import integration_test from test_data_utils import NonTTYTestDataLoader, TestDataLoader class TestNonTTYIntegration(unittest.TestCase): """Integration tests for non-TTY handling across the full workflow.""" - + def setUp(self): """Set up integration test environment with centralized test data.""" self.temp_dir = tempfile.mkdtemp() self.env_manager = HatchEnvironmentManager( - environments_dir=Path(self.temp_dir) / "envs", - simulation_mode=True + environments_dir=Path(self.temp_dir) / "envs", simulation_mode=True ) self.test_data = NonTTYTestDataLoader() self.addCleanup(self._cleanup_temp_dir) - + def _cleanup_temp_dir(self): """Clean up temporary directory.""" import shutil + shutil.rmtree(self.temp_dir, ignore_errors=True) - + @integration_test(scope="component") - @slow_test - @patch('sys.stdin.isatty', return_value=False) + @patch("sys.stdin.isatty", return_value=False) def test_cli_package_add_non_tty(self, mock_isatty): """Test package addition in non-TTY environment via CLI.""" # Create test environment self.env_manager.create_environment("test_env", "Test environment") - + # Test package addition without hanging test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - + # Ensure the test package exists if not pkg_path.exists(): self.skipTest(f"Test package not found: {pkg_path}") - + result = self.env_manager.add_package_to_environment( str(pkg_path), "test_env", - auto_approve=False # Test environment variable handling + auto_approve=False, # Test environment variable handling ) - + self.assertTrue(result, "Package addition should succeed in non-TTY mode") mock_isatty.assert_called() - + @integration_test(scope="component") - @slow_test - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': '1'}) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "1"}) def test_environment_variable_integration(self): """Test HATCH_AUTO_APPROVE environment variable integration.""" # Create test environment self.env_manager.create_environment("test_env", "Test environment") - + # Test with centralized test data test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - + # Ensure the test package exists if not pkg_path.exists(): self.skipTest(f"Test package not found: {pkg_path}") - + result = self.env_manager.add_package_to_environment( str(pkg_path), "test_env", - auto_approve=False # Environment variable should override + auto_approve=False, # Environment variable should override ) - - self.assertTrue(result, "Package addition should succeed with HATCH_AUTO_APPROVE") - + + self.assertTrue( + result, "Package addition should succeed with HATCH_AUTO_APPROVE" + ) + @integration_test(scope="component") - @slow_test - @patch('sys.stdin.isatty', return_value=False) + @patch("sys.stdin.isatty", return_value=False) def test_multiple_package_installation_non_tty(self, mock_isatty): """Test multiple package installation in non-TTY environment.""" # Create test environment self.env_manager.create_environment("test_env", "Test environment") - + test_loader = TestDataLoader() - + # Install first package base_pkg_path = test_loader.packages_dir / "basic" / "base_pkg" if base_pkg_path.exists(): result1 = self.env_manager.add_package_to_environment( - str(base_pkg_path), - "test_env", - auto_approve=False + str(base_pkg_path), "test_env", auto_approve=False ) self.assertTrue(result1, "First package installation should succeed") - + # Install second package utility_pkg_path = test_loader.packages_dir / "basic" / "utility_pkg" if utility_pkg_path.exists(): result2 = self.env_manager.add_package_to_environment( - str(utility_pkg_path), - "test_env", - auto_approve=False + str(utility_pkg_path), "test_env", auto_approve=False ) self.assertTrue(result2, "Second package installation should succeed") - + @integration_test(scope="component") - @slow_test - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': 'true'}) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "true"}) def test_environment_variable_case_insensitive_integration(self): """Test case-insensitive environment variable in full integration.""" # Create test environment self.env_manager.create_environment("test_env", "Test environment") - + test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - + if not pkg_path.exists(): self.skipTest(f"Test package not found: {pkg_path}") - + result = self.env_manager.add_package_to_environment( - str(pkg_path), - "test_env", - auto_approve=False + str(pkg_path), "test_env", auto_approve=False ) - - self.assertTrue(result, "Package addition should succeed with case-insensitive env var") - + + self.assertTrue( + result, "Package addition should succeed with case-insensitive env var" + ) + @integration_test(scope="component") - @slow_test - @patch('sys.stdin.isatty', return_value=True) - @patch.dict(os.environ, {'HATCH_AUTO_APPROVE': 'invalid'}) - @patch('builtins.input', return_value='y') - def test_invalid_environment_variable_fallback_integration(self, mock_input, mock_isatty): + @patch("sys.stdin.isatty", return_value=True) + @patch.dict(os.environ, {"HATCH_AUTO_APPROVE": "invalid"}) + @patch("builtins.input", return_value="y") + def test_invalid_environment_variable_fallback_integration( + self, mock_input, mock_isatty + ): """Test fallback to interactive mode with invalid environment variable.""" # Create test environment self.env_manager.create_environment("test_env", "Test environment") - + test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - + if not pkg_path.exists(): self.skipTest(f"Test package not found: {pkg_path}") - + result = self.env_manager.add_package_to_environment( - str(pkg_path), - "test_env", - auto_approve=False + str(pkg_path), "test_env", auto_approve=False ) - + self.assertTrue(result, "Package addition should succeed with user approval") # Verify that input was called (fallback to interactive mode) mock_input.assert_called() @@ -163,119 +156,113 @@ def test_invalid_environment_variable_fallback_integration(self, mock_input, moc class TestNonTTYErrorScenarios(unittest.TestCase): """Test error scenarios in non-TTY environments.""" - + def setUp(self): """Set up test environment.""" self.temp_dir = tempfile.mkdtemp() self.env_manager = HatchEnvironmentManager( - environments_dir=Path(self.temp_dir) / "envs", - simulation_mode=True + environments_dir=Path(self.temp_dir) / "envs", simulation_mode=True ) self.test_data = NonTTYTestDataLoader() self.addCleanup(self._cleanup_temp_dir) - + def _cleanup_temp_dir(self): """Clean up temporary directory.""" import shutil + shutil.rmtree(self.temp_dir, ignore_errors=True) - + @integration_test(scope="component") - @slow_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', side_effect=KeyboardInterrupt()) + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", side_effect=KeyboardInterrupt()) def test_keyboard_interrupt_integration(self, mock_input, mock_isatty): """Test KeyboardInterrupt handling in full integration.""" # Create test environment self.env_manager.create_environment("test_env", "Test environment") - + test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - + if not pkg_path.exists(): self.skipTest(f"Test package not found: {pkg_path}") - + result = self.env_manager.add_package_to_environment( - str(pkg_path), - "test_env", - auto_approve=False + str(pkg_path), "test_env", auto_approve=False ) - + # Should return False due to user cancellation self.assertFalse(result, "Package installation should be cancelled by user") - + @integration_test(scope="component") - @slow_test - @patch('sys.stdin.isatty', return_value=True) - @patch('builtins.input', side_effect=EOFError()) + @patch("sys.stdin.isatty", return_value=True) + @patch("builtins.input", side_effect=EOFError()) def test_eof_error_integration(self, mock_input, mock_isatty): """Test EOFError handling in full integration.""" # Create test environment self.env_manager.create_environment("test_env", "Test environment") - + test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - + if not pkg_path.exists(): self.skipTest(f"Test package not found: {pkg_path}") - + result = self.env_manager.add_package_to_environment( - str(pkg_path), - "test_env", - auto_approve=False + str(pkg_path), "test_env", auto_approve=False ) - + # Should return False due to EOF error self.assertFalse(result, "Package installation should be cancelled due to EOF") class TestEnvironmentVariableIntegrationScenarios(unittest.TestCase): """Test comprehensive environment variable scenarios in full integration.""" - + def setUp(self): """Set up test environment.""" self.temp_dir = tempfile.mkdtemp() self.env_manager = HatchEnvironmentManager( - environments_dir=Path(self.temp_dir) / "envs", - simulation_mode=True + environments_dir=Path(self.temp_dir) / "envs", simulation_mode=True ) self.test_data = NonTTYTestDataLoader() self.addCleanup(self._cleanup_temp_dir) - + def _cleanup_temp_dir(self): """Clean up temporary directory.""" import shutil + shutil.rmtree(self.temp_dir, ignore_errors=True) - + @integration_test(scope="component") - @slow_test def test_all_valid_environment_variables_integration(self): """Test all valid environment variable values in integration.""" # Create test environment self.env_manager.create_environment("test_env", "Test environment") - + test_loader = TestDataLoader() pkg_path = test_loader.packages_dir / "basic" / "base_pkg" - + if not pkg_path.exists(): self.skipTest(f"Test package not found: {pkg_path}") - + # Test all valid environment variable values valid_values = ["1", "true", "yes", "TRUE", "YES", "True"] - + for i, value in enumerate(valid_values): with self.subTest(env_value=value): env_name = f"test_env_{i}" self.env_manager.create_environment(env_name, f"Test environment {i}") - - with patch.dict(os.environ, {'HATCH_AUTO_APPROVE': value}): + + with patch.dict(os.environ, {"HATCH_AUTO_APPROVE": value}): result = self.env_manager.add_package_to_environment( - str(pkg_path), - env_name, - auto_approve=False + str(pkg_path), env_name, auto_approve=False + ) + + self.assertTrue( + result, + f"Package installation should succeed with env var: {value}", ) - - self.assertTrue(result, f"Package installation should succeed with env var: {value}") -if __name__ == '__main__': +if __name__ == "__main__": unittest.main() diff --git a/tests/test_online_package_loader.py b/tests/test_online_package_loader.py index 32f38f3..33dc7f1 100644 --- a/tests/test_online_package_loader.py +++ b/tests/test_online_package_loader.py @@ -1,4 +1,3 @@ -import sys import unittest import tempfile import shutil @@ -6,26 +5,52 @@ import json import time from pathlib import Path +from unittest.mock import patch -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import integration_test # Import path management removed - using test_data_utils for test dependencies from hatch.environment_manager import HatchEnvironmentManager -from hatch.package_loader import HatchPackageLoader, PackageLoaderError +from hatch.package_loader import HatchPackageLoader from hatch.registry_retriever import RegistryRetriever from hatch.registry_explorer import find_package, get_package_release_url +from hatch.python_environment_manager import PythonEnvironmentManager +from hatch.installers.dependency_installation_orchestrator import ( + DependencyInstallerOrchestrator, +) # Configure logging logging.basicConfig( - level=logging.DEBUG, - format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' + level=logging.DEBUG, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s" ) logger = logging.getLogger("hatch.package_loader_tests") +# Fake registry data matching the structure expected by find_package/get_package_release_url +FAKE_REGISTRY_DATA = { + "repositories": [ + { + "name": "test-repo", + "packages": [ + { + "name": "base_pkg_1", + "latest_version": "1.0.1", + "versions": [ + { + "version": "1.0.1", + "release_uri": "https://fake.url/base_pkg_1-1.0.1.zip", + } + ], + } + ], + } + ] +} + + class OnlinePackageLoaderTests(unittest.TestCase): - """Tests for package downloading and caching functionality using online mode.""" - + """Tests for package downloading and caching functionality with mocked network.""" + def setUp(self): """Set up test environment before each test.""" # Create temporary directories @@ -34,62 +59,131 @@ def setUp(self): self.cache_dir.mkdir(parents=True, exist_ok=True) self.env_dir = Path(self.temp_dir) / "envs" self.env_dir.mkdir(parents=True, exist_ok=True) - - # Initialize registry retriever in online mode + + # Pre-create environments.json and current_env to avoid + # _load_environments triggering create_environment("default") + envs_file = self.env_dir / "environments.json" + envs_file.write_text( + json.dumps( + { + "default": { + "name": "default", + "description": "Default environment", + "packages": [], + } + } + ) + ) + current_env_file = self.env_dir / "current_env" + current_env_file.write_text("default") + + # Start patches to prevent network and subprocess calls + # Mock RegistryRetriever to prevent HTTP calls + patch.object( + RegistryRetriever, + "_fetch_remote_registry", + return_value=FAKE_REGISTRY_DATA, + ).start() + patch.object(RegistryRetriever, "_registry_exists", return_value=True).start() + + # Mock PythonEnvironmentManager to prevent conda/mamba detection + patch.object(PythonEnvironmentManager, "_detect_conda_mamba").start() + patch.object( + PythonEnvironmentManager, "is_available", return_value=False + ).start() + patch.object( + PythonEnvironmentManager, "get_python_executable", return_value=None + ).start() + patch.object( + PythonEnvironmentManager, "get_environment_activation_info", return_value={} + ).start() + + # Initialize registry retriever (will use mocked _fetch_remote_registry) self.retriever = RegistryRetriever( - local_cache_dir=self.cache_dir, - simulation_mode=False # Use online mode + local_cache_dir=self.cache_dir, simulation_mode=False ) - - # Get registry data for test packages + + # Get registry data (returns fake data via mock) self.registry_data = self.retriever.get_registry() - - # Initialize package loader (needed for some lower-level tests) + + # Initialize package loader self.package_loader = HatchPackageLoader(cache_dir=self.cache_dir) - - # Initialize environment manager + + # Initialize environment manager (will use mocked registry and python env) self.env_manager = HatchEnvironmentManager( environments_dir=self.env_dir, cache_dir=self.cache_dir, - simulation_mode=False + simulation_mode=False, ) def tearDown(self): """Clean up test environment after each test.""" - # Remove temporary directory + patch.stopall() shutil.rmtree(self.temp_dir) - + + def _create_package_files(self, package_name, version, env_path): + """Create simulated package files in environment and cache directories.""" + # Create installed package directory with metadata + installed_path = env_path / package_name + installed_path.mkdir(parents=True, exist_ok=True) + metadata = {"name": package_name, "version": version, "type": "hatch"} + (installed_path / "hatch_metadata.json").write_text(json.dumps(metadata)) + + # Create cached package directory with metadata + cache_path = self.cache_dir / "packages" / f"{package_name}-{version}" + cache_path.mkdir(parents=True, exist_ok=True) + (cache_path / "hatch_metadata.json").write_text(json.dumps(metadata)) + @integration_test(scope="service") - @slow_test - def test_download_package_online(self): - """Test downloading a package from online registry.""" - # Use base_pkg_1 for testing since it's mentioned as a reliable test package + @patch.object(DependencyInstallerOrchestrator, "install_dependencies") + def test_download_package_online(self, mock_install): + """Test downloading a package from online registry (mocked).""" package_name = "base_pkg_1" version = "==1.0.1" + # Mock install_dependencies to return success with package info + mock_install.return_value = ( + True, + [ + { + "name": "base_pkg_1", + "version": "1.0.1", + "type": "hatch", + "source": "remote", + } + ], + ) + # Add package to environment using the environment manager result = self.env_manager.add_package_to_environment( package_name, version_constraint=version, - auto_approve=True # Automatically approve installation in tests - ) - self.assertTrue(result, f"Failed to add package {package_name}@{version} to environment") + auto_approve=True, + ) + self.assertTrue( + result, f"Failed to add package {package_name}@{version} to environment" + ) # Verify package is in environment - current_env = self.env_manager.get_current_environment() env_data = self.env_manager.get_current_environment_data() - installed_packages = {pkg["name"]: pkg["version"] for pkg in env_data.get("packages", [])} - self.assertIn(package_name, installed_packages, f"Package {package_name} not found in environment") + installed_packages = { + pkg["name"]: pkg["version"] for pkg in env_data.get("packages", []) + } + self.assertIn( + package_name, + installed_packages, + f"Package {package_name} not found in environment", + ) # def test_multiple_package_versions(self): # """Test downloading multiple versions of the same package.""" # package_name = "base_pkg_1" # versions = ["1.0.0", "1.1.0"] # Test multiple versions if available - + # # Find package data in the registry # package_data = find_package(self.registry_data, package_name) # self.assertIsNotNone(package_data, f"Package '{package_name}' not found in registry") - + # # Try to download each version # for version in versions: # try: @@ -102,101 +196,199 @@ def test_download_package_online(self): # logger.info(f"Successfully downloaded {package_name}@{version}") # except Exception as e: # logger.warning(f"Couldn't download {package_name}@{version}: {e}") - + @integration_test(scope="service") - @slow_test def test_install_and_caching(self): - """Test installing and caching a package.""" + """Test installing and caching a package (mocked).""" package_name = "base_pkg_1" version = "1.0.1" version_constraint = f"=={version}" - # Find package in registry + # Find package in registry (uses fake registry data) package_data = find_package(self.registry_data, package_name) - self.assertIsNotNone(package_data, f"Package {package_name} not found in registry") + self.assertIsNotNone( + package_data, f"Package {package_name} not found in registry" + ) # Create a specific test environment for this test test_env_name = "test_install_env" - self.env_manager.create_environment(test_env_name, "Test environment for installation test") + self.env_manager.create_environment( + test_env_name, "Test environment for installation test" + ) - # Add the package to the environment - try: + # Get environment path for file creation in mock + env_path = self.env_manager.get_environment_path(test_env_name) + + def mock_install_side_effect(*args, **kwargs): + """Simulate package installation by creating expected files.""" + self._create_package_files(package_name, version, env_path) + return ( + True, + [ + { + "name": package_name, + "version": version, + "type": "hatch", + "source": "remote", + } + ], + ) + + with patch.object( + DependencyInstallerOrchestrator, + "install_dependencies", + side_effect=mock_install_side_effect, + ): result = self.env_manager.add_package_to_environment( - package_name, + package_name, env_name=test_env_name, version_constraint=version_constraint, - auto_approve=True # Automatically approve installation in tests + auto_approve=True, ) - - self.assertTrue(result, f"Failed to add package {package_name}@{version_constraint} to environment") - - # Get environment path - env_path = self.env_manager.get_environment_path(test_env_name) + + self.assertTrue( + result, + f"Failed to add package {package_name}@{version_constraint} to environment", + ) + + # Verify installation in environment directory installed_path = env_path / package_name - - # Verify installation - self.assertTrue(installed_path.exists(), f"Package not installed to environment directory: {installed_path}") - self.assertTrue((installed_path / "hatch_metadata.json").exists(), f"Installation missing metadata file: {installed_path / 'hatch_metadata.json'}") + self.assertTrue( + installed_path.exists(), + f"Package not installed to environment directory: {installed_path}", + ) + self.assertTrue( + (installed_path / "hatch_metadata.json").exists(), + f"Installation missing metadata file: {installed_path / 'hatch_metadata.json'}", + ) # Verify the cache contains the package cache_path = self.cache_dir / "packages" / f"{package_name}-{version}" - self.assertTrue(cache_path.exists(), f"Package not cached during installation: {cache_path}") - self.assertTrue((cache_path / "hatch_metadata.json").exists(), f"Cache missing metadata file: {cache_path / 'hatch_metadata.json'}") + self.assertTrue( + cache_path.exists(), + f"Package not cached during installation: {cache_path}", + ) + self.assertTrue( + (cache_path / "hatch_metadata.json").exists(), + f"Cache missing metadata file: {cache_path / 'hatch_metadata.json'}", + ) + + logger.info( + f"Successfully installed and cached package: {package_name}@{version}" + ) - logger.info(f"Successfully installed and cached package: {package_name}@{version}") - except Exception as e: - self.fail(f"Package installation raised exception: {e}") - @integration_test(scope="service") - @slow_test def test_cache_reuse(self): - """Test that the cache is reused for multiple installs.""" + """Test that the cache is reused for multiple installs (mocked).""" package_name = "base_pkg_1" version = "1.0.1" version_constraint = f"=={version}" - # Find package in registry + # Find package in registry (uses fake registry data) package_data = find_package(self.registry_data, package_name) - self.assertIsNotNone(package_data, f"Package {package_name} not found in registry") + self.assertIsNotNone( + package_data, f"Package {package_name} not found in registry" + ) # Get package URL package_url = get_package_release_url(package_data, version_constraint) - self.assertIsNotNone(package_url, f"No download URL found for {package_name}@{version_constraint}") + self.assertIsNotNone( + package_url, + f"No download URL found for {package_name}@{version_constraint}", + ) # Create two test environments first_env = "test_cache_env1" second_env = "test_cache_env2" - self.env_manager.create_environment(first_env, "First test environment for cache test") - self.env_manager.create_environment(second_env, "Second test environment for cache test") - - # First install to create cache - start_time_first = time.time() - result_first = self.env_manager.add_package_to_environment( - package_name, - env_name=first_env, - version_constraint=version_constraint, - auto_approve=True # Automatically approve installation in tests + self.env_manager.create_environment( + first_env, "First test environment for cache test" ) - first_install_time = time.time() - start_time_first - logger.info(f"First installation took {first_install_time:.2f} seconds") - self.assertTrue(result_first, f"Failed to add package {package_name}@{version_constraint} to first environment") - first_env_path = self.env_manager.get_environment_path(first_env) - self.assertTrue((first_env_path / package_name).exists(), f"Package not found at the expected path: {first_env_path / package_name}") - - # Second install - should use cache - start_time = time.time() - result_second = self.env_manager.add_package_to_environment( - package_name, - env_name=second_env, - version_constraint=version_constraint, - auto_approve=True # Automatically approve installation in tests + self.env_manager.create_environment( + second_env, "Second test environment for cache test" ) - install_time = time.time() - start_time - - logger.info(f"Second installation took {install_time:.2f} seconds (should be faster if cache used)") + first_env_path = self.env_manager.get_environment_path(first_env) second_env_path = self.env_manager.get_environment_path(second_env) - self.assertTrue((second_env_path / package_name).exists(), f"Package not found at the expected path: {second_env_path / package_name}") + + def mock_first_install(*args, **kwargs): + """Simulate first install: creates cache and env files.""" + self._create_package_files(package_name, version, first_env_path) + return ( + True, + [ + { + "name": package_name, + "version": version, + "type": "hatch", + "source": "remote", + } + ], + ) + + def mock_second_install(*args, **kwargs): + """Simulate second install: only creates env files (cache exists).""" + installed_path = second_env_path / package_name + installed_path.mkdir(parents=True, exist_ok=True) + metadata = {"name": package_name, "version": version, "type": "hatch"} + (installed_path / "hatch_metadata.json").write_text(json.dumps(metadata)) + return ( + True, + [ + { + "name": package_name, + "version": version, + "type": "hatch", + "source": "cache", + } + ], + ) + + # First install to create cache + with patch.object( + DependencyInstallerOrchestrator, + "install_dependencies", + side_effect=mock_first_install, + ): + start_time_first = time.time() + result_first = self.env_manager.add_package_to_environment( + package_name, + env_name=first_env, + version_constraint=version_constraint, + auto_approve=True, + ) + first_install_time = time.time() - start_time_first + logger.info(f"First installation took {first_install_time:.2f} seconds") + self.assertTrue( + result_first, + f"Failed to add package {package_name}@{version_constraint} to first environment", + ) + self.assertTrue( + (first_env_path / package_name).exists(), + f"Package not found at the expected path: {first_env_path / package_name}", + ) + + # Second install - should use cache + with patch.object( + DependencyInstallerOrchestrator, + "install_dependencies", + side_effect=mock_second_install, + ): + start_time = time.time() + self.env_manager.add_package_to_environment( + package_name, + env_name=second_env, + version_constraint=version_constraint, + auto_approve=True, + ) + install_time = time.time() - start_time + logger.info( + f"Second installation took {install_time:.2f} seconds (should be faster if cache used)" + ) + self.assertTrue( + (second_env_path / package_name).exists(), + f"Package not found at the expected path: {second_env_path / package_name}", + ) + if __name__ == "__main__": unittest.main() diff --git a/tests/test_python_environment_manager.py b/tests/test_python_environment_manager.py index 0652d46..fd2ead7 100644 --- a/tests/test_python_environment_manager.py +++ b/tests/test_python_environment_manager.py @@ -3,15 +3,21 @@ This module contains tests for the Python environment management functionality, including conda/mamba environment creation, configuration, and integration. """ + +import json +import platform import shutil import tempfile import unittest from pathlib import Path -from unittest.mock import Mock, patch, MagicMock +from unittest.mock import Mock, patch -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test, integration_test -from hatch.python_environment_manager import PythonEnvironmentManager, PythonEnvironmentError +from hatch.python_environment_manager import ( + PythonEnvironmentManager, + PythonEnvironmentError, +) class TestPythonEnvironmentManager(unittest.TestCase): @@ -32,7 +38,7 @@ def setUp(self): def tearDown(self): """Clean up test environment.""" # Clean up any conda/mamba environments created during this test - if hasattr(self, 'manager') and self.manager.is_available(): + if hasattr(self, "manager") and self.manager.is_available(): for env_name in self.created_environments: try: if self.manager.environment_exists(env_name): @@ -49,65 +55,122 @@ def _track_environment(self, env_name): self.created_environments.append(env_name) @regression_test - @patch('hatch.python_environment_manager.PythonEnvironmentManager._conda_env_exists', return_value=True) - @patch('hatch.python_environment_manager.PythonEnvironmentManager._get_conda_env_name', return_value='hatch_test_env') - @patch('hatch.python_environment_manager.PythonEnvironmentManager._get_python_executable_path', return_value='C:/fake/env/Scripts/python.exe') - @patch('hatch.python_environment_manager.PythonEnvironmentManager.get_environment_path', return_value=Path('C:/fake/env')) - @patch('platform.system', return_value='Windows') - def test_get_environment_activation_info_windows(self, mock_platform, mock_get_env_path, mock_get_python_exec_path, mock_get_conda_env_name, mock_conda_env_exists): + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._conda_env_exists", + return_value=True, + ) + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._get_conda_env_name", + return_value="hatch_test_env", + ) + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._get_python_executable_path", + return_value="C:/fake/env/Scripts/python.exe", + ) + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager.get_environment_path", + return_value=Path("C:/fake/env"), + ) + @unittest.skipUnless( + platform.system() == "Windows", "Windows-specific path separator test" + ) + @patch("platform.system", return_value="Windows") + def test_get_environment_activation_info_windows( + self, + mock_platform, + mock_get_env_path, + mock_get_python_exec_path, + mock_get_conda_env_name, + mock_conda_env_exists, + ): """Test get_environment_activation_info returns correct env vars on Windows.""" - env_name = 'test_env' - manager = PythonEnvironmentManager(environments_dir=Path('C:/fake/envs')) + env_name = "test_env" + manager = PythonEnvironmentManager(environments_dir=Path("C:/fake/envs")) env_vars = manager.get_environment_activation_info(env_name) self.assertIsInstance(env_vars, dict) - self.assertEqual(env_vars['CONDA_DEFAULT_ENV'], 'hatch_test_env') - self.assertEqual(env_vars['CONDA_PREFIX'], str(Path('C:/fake/env'))) - self.assertIn('PATH', env_vars) + self.assertEqual(env_vars["CONDA_DEFAULT_ENV"], "hatch_test_env") + self.assertEqual(env_vars["CONDA_PREFIX"], str(Path("C:/fake/env"))) + self.assertIn("PATH", env_vars) # On Windows, the path separator is ';' and paths are backslash # Split PATH and check each expected directory is present as a component - path_dirs = env_vars['PATH'].split(';') - self.assertIn('C:\\fake\\env', path_dirs) - self.assertIn('C:\\fake\\env\\Scripts', path_dirs) - self.assertIn('C:\\fake\\env\\Library\\bin', path_dirs) - self.assertEqual(env_vars['PYTHON'], 'C:/fake/env/Scripts/python.exe') + path_dirs = env_vars["PATH"].split(";") + self.assertIn("C:\\fake\\env", path_dirs) + self.assertIn("C:\\fake\\env\\Scripts", path_dirs) + self.assertIn("C:\\fake\\env\\Library\\bin", path_dirs) + self.assertEqual(env_vars["PYTHON"], "C:/fake/env/Scripts/python.exe") @regression_test - @patch('hatch.python_environment_manager.PythonEnvironmentManager._conda_env_exists', return_value=True) - @patch('hatch.python_environment_manager.PythonEnvironmentManager._get_conda_env_name', return_value='hatch_test_env') - @patch('hatch.python_environment_manager.PythonEnvironmentManager._get_python_executable_path', return_value='/fake/env/bin/python') - @patch('hatch.python_environment_manager.PythonEnvironmentManager.get_environment_path', return_value=Path('/fake/env')) - @patch('platform.system', return_value='Linux') - def test_get_environment_activation_info_unix(self, mock_platform, mock_get_env_path, mock_get_python_exec_path, mock_get_conda_env_name, mock_conda_env_exists): + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._conda_env_exists", + return_value=True, + ) + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._get_conda_env_name", + return_value="hatch_test_env", + ) + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._get_python_executable_path", + return_value="/fake/env/bin/python", + ) + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager.get_environment_path", + return_value=Path("/fake/env"), + ) + @patch("platform.system", return_value="Linux") + def test_get_environment_activation_info_unix( + self, + mock_platform, + mock_get_env_path, + mock_get_python_exec_path, + mock_get_conda_env_name, + mock_conda_env_exists, + ): """Test get_environment_activation_info returns correct env vars on Unix.""" - env_name = 'test_env' - manager = PythonEnvironmentManager(environments_dir=Path('/fake/envs')) + env_name = "test_env" + manager = PythonEnvironmentManager(environments_dir=Path("/fake/envs")) env_vars = manager.get_environment_activation_info(env_name) self.assertIsInstance(env_vars, dict) - self.assertEqual(env_vars['CONDA_DEFAULT_ENV'], 'hatch_test_env') - self.assertEqual(env_vars['CONDA_PREFIX'], str(Path('/fake/env'))) - self.assertIn('PATH', env_vars) + self.assertEqual(env_vars["CONDA_DEFAULT_ENV"], "hatch_test_env") + self.assertEqual(env_vars["CONDA_PREFIX"], str(Path("/fake/env"))) + self.assertIn("PATH", env_vars) # On Unix, the path separator is ':' and paths are forward slash, but Path() may normalize to backslash on Windows # Accept both possible representations for cross-platform test running - path_dirs = env_vars['PATH'] - self.assertTrue('/fake/env/bin' in path_dirs or '\\fake\\env\\bin' in path_dirs, f"Expected '/fake/env/bin' or '\\fake\\env\\bin' to be in PATH: {env_vars['PATH']}") - self.assertEqual(env_vars['PYTHON'], '/fake/env/bin/python') + path_dirs = env_vars["PATH"] + self.assertTrue( + "/fake/env/bin" in path_dirs or "\\fake\\env\\bin" in path_dirs, + f"Expected '/fake/env/bin' or '\\fake\\env\\bin' to be in PATH: {env_vars['PATH']}", + ) + self.assertEqual(env_vars["PYTHON"], "/fake/env/bin/python") @regression_test - @patch('hatch.python_environment_manager.PythonEnvironmentManager._conda_env_exists', return_value=False) - def test_get_environment_activation_info_env_not_exists(self, mock_conda_env_exists): + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._conda_env_exists", + return_value=False, + ) + def test_get_environment_activation_info_env_not_exists( + self, mock_conda_env_exists + ): """Test get_environment_activation_info returns None if env does not exist.""" - env_name = 'nonexistent_env' - manager = PythonEnvironmentManager(environments_dir=Path('/fake/envs')) + env_name = "nonexistent_env" + manager = PythonEnvironmentManager(environments_dir=Path("/fake/envs")) env_vars = manager.get_environment_activation_info(env_name) self.assertIsNone(env_vars) @regression_test - @patch('hatch.python_environment_manager.PythonEnvironmentManager._conda_env_exists', return_value=True) - @patch('hatch.python_environment_manager.PythonEnvironmentManager._get_python_executable_path', return_value=None) - def test_get_environment_activation_info_no_python(self, mock_get_python_exec_path, mock_conda_env_exists): + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._conda_env_exists", + return_value=True, + ) + @patch( + "hatch.python_environment_manager.PythonEnvironmentManager._get_python_executable_path", + return_value=None, + ) + def test_get_environment_activation_info_no_python( + self, mock_get_python_exec_path, mock_conda_env_exists + ): """Test get_environment_activation_info returns None if python executable not found.""" - env_name = 'test_env' - manager = PythonEnvironmentManager(environments_dir=Path('/fake/envs')) + env_name = "test_env" + manager = PythonEnvironmentManager(environments_dir=Path("/fake/envs")) env_vars = manager.get_environment_activation_info(env_name) self.assertIsNone(env_vars) @@ -122,7 +185,9 @@ def test_detect_conda_mamba_with_mamba(self): """Test conda/mamba detection when mamba is available.""" with patch.object(PythonEnvironmentManager, "_detect_manager") as mock_detect: # mamba found, conda found - mock_detect.side_effect = lambda manager: "/usr/bin/mamba" if manager == "mamba" else "/usr/bin/conda" + mock_detect.side_effect = lambda manager: ( + "/usr/bin/mamba" if manager == "mamba" else "/usr/bin/conda" + ) manager = PythonEnvironmentManager(environments_dir=self.environments_dir) self.assertEqual(manager.mamba_executable, "/usr/bin/mamba") self.assertEqual(manager.conda_executable, "/usr/bin/conda") @@ -132,7 +197,9 @@ def test_detect_conda_mamba_conda_only(self): """Test conda/mamba detection when only conda is available.""" with patch.object(PythonEnvironmentManager, "_detect_manager") as mock_detect: # mamba not found, conda found - mock_detect.side_effect = lambda manager: None if manager == "mamba" else "/usr/bin/conda" + mock_detect.side_effect = lambda manager: ( + None if manager == "mamba" else "/usr/bin/conda" + ) manager = PythonEnvironmentManager(environments_dir=self.environments_dir) self.assertIsNone(manager.mamba_executable) self.assertEqual(manager.conda_executable, "/usr/bin/conda") @@ -140,7 +207,9 @@ def test_detect_conda_mamba_conda_only(self): @regression_test def test_detect_conda_mamba_none_available(self): """Test conda/mamba detection when neither is available.""" - with patch.object(PythonEnvironmentManager, "_detect_manager", return_value=None): + with patch.object( + PythonEnvironmentManager, "_detect_manager", return_value=None + ): manager = PythonEnvironmentManager(environments_dir=self.environments_dir) self.assertIsNone(manager.mamba_executable) self.assertIsNone(manager.conda_executable) @@ -153,16 +222,15 @@ def test_get_conda_env_name(self): self.assertEqual(conda_name, "hatch_test_env") @regression_test - @patch('subprocess.run') + @patch("subprocess.run") def test_get_python_executable_path_windows(self, mock_run): """Test Python executable path on Windows.""" - with patch('platform.system', return_value='Windows'): + with patch("platform.system", return_value="Windows"): env_name = "test_env" # Mock conda info command to return environment path mock_run.return_value = Mock( - returncode=0, - stdout='{"envs": ["/conda/envs/hatch_test_env"]}' + returncode=0, stdout='{"envs": ["/conda/envs/hatch_test_env"]}' ) python_path = self.manager._get_python_executable_path(env_name) @@ -170,16 +238,15 @@ def test_get_python_executable_path_windows(self, mock_run): self.assertEqual(python_path, expected) @regression_test - @patch('subprocess.run') + @patch("subprocess.run") def test_get_python_executable_path_unix(self, mock_run): """Test Python executable path on Unix/Linux.""" - with patch('platform.system', return_value='Linux'): + with patch("platform.system", return_value="Linux"): env_name = "test_env" # Mock conda info command to return environment path mock_run.return_value = Mock( - returncode=0, - stdout='{"envs": ["/conda/envs/hatch_test_env"]}' + returncode=0, stdout='{"envs": ["/conda/envs/hatch_test_env"]}' ) python_path = self.manager._get_python_executable_path(env_name) @@ -192,11 +259,11 @@ def test_is_available_no_conda(self): manager = PythonEnvironmentManager(environments_dir=self.environments_dir) manager.conda_executable = None manager.mamba_executable = None - + self.assertFalse(manager.is_available()) @regression_test - @patch('subprocess.run') + @patch("subprocess.run") def test_is_available_with_conda(self, mock_run): """Test availability check when conda is available.""" self.manager.conda_executable = "/usr/bin/conda" @@ -223,12 +290,14 @@ def test_get_preferred_executable(self): self.assertIsNone(self.manager.get_preferred_executable()) @regression_test - @patch('shutil.which') - @patch('subprocess.run') + @patch("shutil.which") + @patch("subprocess.run") def test_create_python_environment_success(self, mock_run, mock_which): """Test successful Python environment creation.""" # Patch mamba detection - mock_which.side_effect = lambda cmd: "/usr/bin/mamba" if cmd == "mamba" else None + mock_which.side_effect = lambda cmd: ( + "/usr/bin/mamba" if cmd == "mamba" else None + ) # Patch subprocess.run for both validation and creation def run_side_effect(cmd, *args, **kwargs): @@ -240,13 +309,16 @@ def run_side_effect(cmd, *args, **kwargs): return Mock(returncode=0, stdout="Environment created") else: return Mock(returncode=0, stdout="") + mock_run.side_effect = run_side_effect - + manager = PythonEnvironmentManager(environments_dir=self.environments_dir) - + # Mock environment existence check - with patch.object(manager, '_conda_env_exists', return_value=False): - result = manager.create_python_environment("test_env", python_version="3.11") + with patch.object(manager, "_conda_env_exists", return_value=False): + result = manager.create_python_environment( + "test_env", python_version="3.11" + ) self.assertTrue(result) mock_run.assert_called() @@ -260,12 +332,14 @@ def test_create_python_environment_no_conda(self): self.manager.create_python_environment("test_env") @regression_test - @patch('shutil.which') - @patch('subprocess.run') + @patch("shutil.which") + @patch("subprocess.run") def test_create_python_environment_already_exists(self, mock_run, mock_which): """Test Python environment creation when environment already exists.""" # Patch mamba detection - mock_which.side_effect = lambda cmd: "/usr/bin/mamba" if cmd == "mamba" else None + mock_which.side_effect = lambda cmd: ( + "/usr/bin/mamba" if cmd == "mamba" else None + ) # Patch subprocess.run for both validation and creation def run_side_effect(cmd, *args, **kwargs): @@ -277,18 +351,21 @@ def run_side_effect(cmd, *args, **kwargs): return Mock(returncode=0, stdout="Environment created") else: return Mock(returncode=0, stdout="") + mock_run.side_effect = run_side_effect # Mock environment already exists - with patch.object(self.manager, '_conda_env_exists', return_value=True): + with patch.object(self.manager, "_conda_env_exists", return_value=True): result = self.manager.create_python_environment("test_env") self.assertTrue(result) # Ensure 'create' was not called, but 'info' was - create_calls = [call for call in mock_run.call_args_list if "create" in call[0][0]] + create_calls = [ + call for call in mock_run.call_args_list if "create" in call[0][0] + ] self.assertEqual(len(create_calls), 0) @regression_test - @patch('subprocess.run') + @patch("subprocess.run") def test_conda_env_exists(self, mock_run): """Test conda environment existence check.""" env_name = "test_env" @@ -296,27 +373,26 @@ def test_conda_env_exists(self, mock_run): # Mock conda env list to return the environment mock_run.return_value = Mock( returncode=0, - stdout='{"envs": ["/conda/envs/hatch_test_env", "/conda/envs/other_env"]}' + stdout='{"envs": ["/conda/envs/hatch_test_env", "/conda/envs/other_env"]}', ) self.assertTrue(self.manager._conda_env_exists(env_name)) @regression_test - @patch('subprocess.run') + @patch("subprocess.run") def test_conda_env_not_exists(self, mock_run): """Test conda environment existence check when environment doesn't exist.""" env_name = "nonexistent_env" - + # Mock conda env list to not return the environment mock_run.return_value = Mock( - returncode=0, - stdout='{"envs": ["/conda/envs/other_env"]}' + returncode=0, stdout='{"envs": ["/conda/envs/other_env"]}' ) - + self.assertFalse(self.manager._conda_env_exists(env_name)) @regression_test - @patch('subprocess.run') + @patch("subprocess.run") def test_get_python_executable_exists(self, mock_run): """Test getting Python executable when environment exists.""" env_name = "test_env" @@ -324,19 +400,24 @@ def test_get_python_executable_exists(self, mock_run): # Mock conda env list to show environment exists def run_side_effect(cmd, *args, **kwargs): if "env" in cmd and "list" in cmd: - return Mock(returncode=0, stdout='{"envs": ["/conda/envs/hatch_test_env"]}') + return Mock( + returncode=0, stdout='{"envs": ["/conda/envs/hatch_test_env"]}' + ) elif "info" in cmd and "--envs" in cmd: - return Mock(returncode=0, stdout='{"envs": ["/conda/envs/hatch_test_env"]}') + return Mock( + returncode=0, stdout='{"envs": ["/conda/envs/hatch_test_env"]}' + ) else: - return Mock(returncode=0, stdout='{}') + return Mock(returncode=0, stdout="{}") mock_run.side_effect = run_side_effect # Mock that the file exists - with patch('pathlib.Path.exists', return_value=True): + with patch("pathlib.Path.exists", return_value=True): result = self.manager.get_python_executable(env_name) import platform from pathlib import Path as _Path + if platform.system() == "Windows": expected = str(_Path("\\conda\\envs\\hatch_test_env\\python.exe")) else: @@ -348,14 +429,14 @@ def test_get_python_executable_not_exists(self): """Test getting Python executable when environment doesn't exist.""" env_name = "nonexistent_env" - with patch.object(self.manager, '_conda_env_exists', return_value=False): + with patch.object(self.manager, "_conda_env_exists", return_value=False): result = self.manager.get_python_executable(env_name) self.assertIsNone(result) class TestPythonEnvironmentManagerIntegration(unittest.TestCase): """Integration test cases for PythonEnvironmentManager with real conda/mamba operations. - + These tests require conda or mamba to be installed on the system and will create real conda environments for testing. They are more comprehensive but slower than the mocked unit tests. @@ -363,21 +444,32 @@ class TestPythonEnvironmentManagerIntegration(unittest.TestCase): @classmethod def setUpClass(cls): - """Set up class-level test environment.""" + """Set up class-level test environment. + + All tests in this class are mocked β€” no real conda/mamba environments + are created. The manager is initialised with fake executables so that + subprocess calls can be intercepted by per-test mocks. + """ cls.temp_dir = tempfile.mkdtemp() cls.environments_dir = Path(cls.temp_dir) / "envs" cls.environments_dir.mkdir(exist_ok=True) - # Create manager instance for integration testing - cls.manager = PythonEnvironmentManager(environments_dir=cls.environments_dir) + # Create manager with mocked detection to avoid real subprocess calls + with patch.object(PythonEnvironmentManager, "_detect_conda_mamba"): + cls.manager = PythonEnvironmentManager( + environments_dir=cls.environments_dir + ) + # Set fake executables so is_available() returns True + cls.manager.mamba_executable = "/usr/bin/mamba" + cls.manager.conda_executable = "/usr/bin/conda" + + # Shared environment names (referenced by tests, but never created for real) + cls.shared_env_basic = "test_shared_basic" + cls.shared_env_py311 = "test_shared_py311" - # Track all environments created during integration tests + # Track environments (kept for API compatibility with setUp/tearDown) cls.all_created_environments = set() - # Skip all tests if conda/mamba is not available - if not cls.manager.is_available(): - raise unittest.SkipTest("Conda/mamba not available for integration tests") - def setUp(self): """Set up individual test.""" # Track environments created during this specific test @@ -403,41 +495,22 @@ def _track_environment(self, env_name): @classmethod def tearDownClass(cls): """Clean up class-level test environment.""" - # Clean up any remaining test environments - try: - # Clean up tracked environments - for env_name in list(cls.all_created_environments): - if cls.manager.environment_exists(env_name): - cls.manager.remove_python_environment(env_name) - - # Clean up known test environment patterns (fallback) - known_patterns = [ - "test_integration_env", "test_python_311", "test_python_312", "test_diagnostics_env", - "test_env_1", "test_env_2", "test_env_3", "test_env_4", "test_env_5", - "test_python_39", "test_python_310", "test_python_312", "test_cache_env1", "test_cache_env2" - ] - for env_name in known_patterns: - if cls.manager.environment_exists(env_name): - cls.manager.remove_python_environment(env_name) - except Exception: - pass # Best effort cleanup - shutil.rmtree(cls.temp_dir, ignore_errors=True) @integration_test(scope="system") - @slow_test def test_conda_mamba_detection_real(self): - """Test real conda/mamba detection on the system.""" + """Test conda/mamba detection logic with mocked executables.""" + # Manager already has fake executables set in setUpClass manager_info = self.manager.get_manager_info() - # At least one should be available since we skip tests if neither is available + # At least one should be available self.assertTrue(manager_info["is_available"]) self.assertTrue( - manager_info["conda_executable"] is not None or - manager_info["mamba_executable"] is not None + manager_info["conda_executable"] is not None + or manager_info["mamba_executable"] is not None ) - # Preferred manager should be set + # Preferred manager should be set (mamba preferred over conda) self.assertIsNotNone(manager_info["preferred_manager"]) # Platform and Python version should be populated @@ -445,9 +518,21 @@ def test_conda_mamba_detection_real(self): self.assertIsNotNone(manager_info["python_version"]) @integration_test(scope="system") - @slow_test - def test_manager_diagnostics_real(self): - """Test real manager diagnostics.""" + @patch("subprocess.run") + def test_manager_diagnostics_real(self, mock_run): + """Test manager diagnostics with mocked subprocess calls.""" + + # Mock subprocess.run for --version calls made by get_manager_diagnostics + def version_side_effect(cmd, *args, **kwargs): + if "--version" in cmd: + if "conda" in cmd[0]: + return Mock(returncode=0, stdout="conda 24.1.0") + elif "mamba" in cmd[0]: + return Mock(returncode=0, stdout="mamba 1.5.6") + return Mock(returncode=0, stdout="") + + mock_run.side_effect = version_side_effect + diagnostics = self.manager.get_manager_diagnostics() # Should have basic information @@ -467,11 +552,48 @@ def test_manager_diagnostics_real(self): self.assertIn("mamba_version", diagnostics) @integration_test(scope="system") - @slow_test - def test_create_and_remove_python_environment_real(self): - """Test real Python environment creation and removal.""" + @patch("subprocess.run") + def test_create_and_remove_python_environment_real(self, mock_run): + """Test Python environment creation and removal with mocked subprocess. + + Mocks subprocess.run to simulate conda create/remove/list/info commands + while preserving the full create β†’ verify β†’ info β†’ remove β†’ verify flow. + """ env_name = "test_integration_env" self._track_environment(env_name) + conda_env_name = f"hatch_{env_name}" + env_path = f"/conda/envs/{conda_env_name}" + + # Track environment state across subprocess calls + env_exists = [False] + + def subprocess_side_effect(cmd, *args, **kwargs): + cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd) + # env list / info --envs: return env list based on current state + if ("env" in cmd_str and "list" in cmd_str) or ( + "info" in cmd_str and "--envs" in cmd_str + ): + if env_exists[0]: + return Mock( + returncode=0, + stdout=f'{{"envs": ["{env_path}"]}}', + ) + else: + return Mock(returncode=0, stdout='{"envs": []}') + # create: mark environment as created + elif "create" in cmd_str: + env_exists[0] = True + return Mock(returncode=0, stdout="Environment created") + # remove: mark environment as removed + elif "remove" in cmd_str: + env_exists[0] = False + return Mock(returncode=0, stdout="Environment removed") + # python --version + elif "--version" in cmd_str and "python" in cmd_str.lower(): + return Mock(returncode=0, stdout="Python 3.12.0") + return Mock(returncode=0, stdout="") + + mock_run.side_effect = subprocess_side_effect # Ensure environment doesn't exist initially if self.manager.environment_exists(env_name): @@ -480,81 +602,120 @@ def test_create_and_remove_python_environment_real(self): # Create environment result = self.manager.create_python_environment(env_name) self.assertTrue(result, "Failed to create Python environment") - + # Verify environment exists self.assertTrue(self.manager.environment_exists(env_name)) - - # Verify Python executable is available - python_exec = self.manager.get_python_executable(env_name) - self.assertIsNotNone(python_exec, "Python executable not found") - self.assertTrue(Path(python_exec).exists(), f"Python executable doesn't exist: {python_exec}") - - # Get environment info - env_info = self.manager.get_environment_info(env_name) + + # Verify Python executable is available (mock Path.exists for the exec) + with patch("pathlib.Path.exists", return_value=True): + python_exec = self.manager.get_python_executable(env_name) + self.assertIsNotNone(python_exec, "Python executable not found") + + # Get environment info (mock Path.exists for python exec check) + with patch("pathlib.Path.exists", return_value=True): + env_info = self.manager.get_environment_info(env_name) self.assertIsNotNone(env_info) self.assertEqual(env_info["environment_name"], env_name) self.assertIsNotNone(env_info["conda_env_name"]) self.assertIsNotNone(env_info["python_executable"]) - + # Remove environment result = self.manager.remove_python_environment(env_name) self.assertTrue(result, "Failed to remove Python environment") - + # Verify environment no longer exists self.assertFalse(self.manager.environment_exists(env_name)) @integration_test(scope="system") - @slow_test - def test_create_python_environment_with_version_real(self): - """Test real Python environment creation with specific version.""" - env_name = "test_python_311" - self._track_environment(env_name) - python_version = "3.11" - - # Ensure environment doesn't exist initially - if self.manager.environment_exists(env_name): - self.manager.remove_python_environment(env_name) - - # Create environment with specific Python version - result = self.manager.create_python_environment(env_name, python_version=python_version) - self.assertTrue(result, f"Failed to create Python {python_version} environment") + @patch("subprocess.run") + def test_create_python_environment_with_version_real(self, mock_run): + """Test Python environment with specific version using mocked subprocess. + + Mocks subprocess to simulate an environment with Python 3.11 installed. + """ + env_name = self.shared_env_py311 + conda_env_name = f"hatch_{env_name}" + env_path = f"/conda/envs/{conda_env_name}" + + def subprocess_side_effect(cmd, *args, **kwargs): + cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd) + # env list / info --envs: environment exists + if ("env" in cmd_str and "list" in cmd_str) or ( + "info" in cmd_str and "--envs" in cmd_str + ): + return Mock( + returncode=0, + stdout=f'{{"envs": ["{env_path}"]}}', + ) + # python --version + elif "--version" in cmd_str: + return Mock(returncode=0, stdout="Python 3.11.8") + return Mock(returncode=0, stdout="") + + mock_run.side_effect = subprocess_side_effect # Verify environment exists - self.assertTrue(self.manager.environment_exists(env_name)) + self.assertTrue( + self.manager.environment_exists(env_name), + f"Mocked environment {env_name} should exist", + ) - # Verify Python version - actual_version = self.manager.get_python_version(env_name) + # Verify Python version (mock Path.exists for python exec) + with patch("pathlib.Path.exists", return_value=True): + actual_version = self.manager.get_python_version(env_name) self.assertIsNotNone(actual_version) - self.assertTrue(actual_version.startswith("3.11"), f"Expected Python 3.11.x, got {actual_version}") + self.assertTrue( + actual_version.startswith("3.11"), + f"Expected Python 3.11.x, got {actual_version}", + ) # Get comprehensive environment info - env_info = self.manager.get_environment_info(env_name) + with patch("pathlib.Path.exists", return_value=True): + env_info = self.manager.get_environment_info(env_name) self.assertIsNotNone(env_info) - self.assertTrue(env_info["python_version"].startswith("3.11"), f"Expected Python 3.11.x, got {env_info['python_version']}") - - # Cleanup - self.manager.remove_python_environment(env_name) + self.assertTrue( + env_info["python_version"].startswith("3.11"), + f"Expected Python 3.11.x, got {env_info['python_version']}", + ) @integration_test(scope="system") - @slow_test - def test_environment_diagnostics_real(self): - """Test real environment diagnostics.""" - env_name = "test_diagnostics_env" - - # Ensure environment doesn't exist initially - if self.manager.environment_exists(env_name): - self.manager.remove_python_environment(env_name) + @patch("subprocess.run") + def test_environment_diagnostics_real(self, mock_run): + """Test environment diagnostics with mocked subprocess calls. + + Tests both non-existent and existing environment diagnostics. + """ + env_name = self.shared_env_basic + conda_env_name = f"hatch_{env_name}" + env_path = f"/conda/envs/{conda_env_name}" + + def subprocess_side_effect(cmd, *args, **kwargs): + cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd) + # env list / info --envs: check if we're querying for the existing env + if ("env" in cmd_str and "list" in cmd_str) or ( + "info" in cmd_str and "--envs" in cmd_str + ): + # Always return the shared env (non-existent env won't match) + return Mock( + returncode=0, + stdout=f'{{"envs": ["{env_path}"]}}', + ) + # python --version + elif "--version" in cmd_str: + return Mock(returncode=0, stdout="Python 3.12.0") + return Mock(returncode=0, stdout="") + + mock_run.side_effect = subprocess_side_effect # Test diagnostics for non-existent environment - diagnostics = self.manager.get_environment_diagnostics(env_name) + nonexistent_env = "test_nonexistent_diagnostics" + diagnostics = self.manager.get_environment_diagnostics(nonexistent_env) self.assertFalse(diagnostics["exists"]) self.assertTrue(diagnostics["conda_available"]) - # Create environment - self.manager.create_python_environment(env_name) - # Test diagnostics for existing environment - diagnostics = self.manager.get_environment_diagnostics(env_name) + with patch("pathlib.Path.exists", return_value=True): + diagnostics = self.manager.get_environment_diagnostics(env_name) self.assertTrue(diagnostics["exists"]) self.assertIsNotNone(diagnostics["python_executable"]) self.assertTrue(diagnostics["python_accessible"]) @@ -564,14 +725,40 @@ def test_environment_diagnostics_real(self): self.assertIsNotNone(diagnostics["environment_path"]) self.assertTrue(diagnostics["environment_path_exists"]) - # Cleanup - self.manager.remove_python_environment(env_name) - @integration_test(scope="system") - @slow_test - def test_force_recreation_real(self): - """Test force recreation of existing environment.""" + @patch("subprocess.run") + def test_force_recreation_real(self, mock_run): + """Test force recreation of existing environment with mocked subprocess.""" env_name = "test_integration_env" + conda_env_name = f"hatch_{env_name}" + env_path = f"/conda/envs/{conda_env_name}" + + # Track environment state + env_exists = [False] + + def subprocess_side_effect(cmd, *args, **kwargs): + cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd) + if ("env" in cmd_str and "list" in cmd_str) or ( + "info" in cmd_str and "--envs" in cmd_str + ): + if env_exists[0]: + return Mock( + returncode=0, + stdout=f'{{"envs": ["{env_path}"]}}', + ) + else: + return Mock(returncode=0, stdout='{"envs": []}') + elif "create" in cmd_str: + env_exists[0] = True + return Mock(returncode=0, stdout="Environment created") + elif "remove" in cmd_str: + env_exists[0] = False + return Mock(returncode=0, stdout="Environment removed") + elif "--version" in cmd_str: + return Mock(returncode=0, stdout="Python 3.12.0") + return Mock(returncode=0, stdout="") + + mock_run.side_effect = subprocess_side_effect # Ensure environment doesn't exist initially if self.manager.environment_exists(env_name): @@ -582,7 +769,8 @@ def test_force_recreation_real(self): self.assertTrue(result1) # Get initial Python executable - python_exec1 = self.manager.get_python_executable(env_name) + with patch("pathlib.Path.exists", return_value=True): + python_exec1 = self.manager.get_python_executable(env_name) self.assertIsNotNone(python_exec1) # Try to create again without force (should succeed but not recreate) @@ -595,78 +783,110 @@ def test_force_recreation_real(self): # Verify environment still exists and works self.assertTrue(self.manager.environment_exists(env_name)) - python_exec3 = self.manager.get_python_executable(env_name) + with patch("pathlib.Path.exists", return_value=True): + python_exec3 = self.manager.get_python_executable(env_name) self.assertIsNotNone(python_exec3) - + # Cleanup self.manager.remove_python_environment(env_name) @integration_test(scope="system") - @slow_test - def test_list_environments_real(self): - """Test listing environments with real conda environments.""" - test_envs = ["test_env_1", "test_env_2"] - final_names = ["hatch_test_env_1", "hatch_test_env_2"] - - # Track environments for cleanup - for env_name in test_envs: - self._track_environment(env_name) - - # Clean up any existing test environments - for env_name in test_envs: - if self.manager.environment_exists(env_name): - self.manager.remove_python_environment(env_name) - - # Create test environments - for env_name in test_envs: - result = self.manager.create_python_environment(env_name) - self.assertTrue(result, f"Failed to create {env_name}") + @patch("subprocess.run") + def test_list_environments_real(self, mock_run): + """Test listing environments with mocked subprocess.""" + shared_basic = f"hatch_{self.shared_env_basic}" + shared_py311 = f"hatch_{self.shared_env_py311}" + + mock_run.return_value = Mock( + returncode=0, + stdout=( + f'{{"envs": ["/conda/envs/{shared_basic}",' + f' "/conda/envs/{shared_py311}"]}}' + ), + ) # List environments env_list = self.manager.list_environments() - # Should include our test environments - for env_name in final_names: - self.assertIn(env_name, env_list, f"{env_name} not found in environment list") + # Should include our shared test environments + for env_name in [shared_basic, shared_py311]: + self.assertIn( + env_name, env_list, f"{env_name} not found in environment list" + ) - # Cleanup - for env_name in final_names: - self.manager.remove_python_environment(env_name) + # Verify list_environments returns a list + self.assertIsInstance(env_list, list) + self.assertGreater(len(env_list), 0, "Environment list should not be empty") @integration_test(scope="system") - @slow_test - @unittest.skipIf( - not (Path("/usr/bin/python3.12").exists() or Path("/usr/bin/python3.9").exists()), - "Multiple Python versions not available for testing" - ) - def test_multiple_python_versions_real(self): + @patch("subprocess.run") + def test_multiple_python_versions_real(self, mock_run): """Test creating environments with multiple Python versions.""" - test_cases = [ - ("test_python_39", "3.9"), - ("test_python_312", "3.12") - ] - + test_cases = [("test_python_39", "3.9"), ("test_python_312", "3.12")] + + # Track which environments exist + existing_envs = {} + + def subprocess_side_effect(cmd, *args, **kwargs): + cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd) + if ("env" in cmd_str and "list" in cmd_str) or ( + "info" in cmd_str and "--envs" in cmd_str + ): + env_paths = [f"/conda/envs/{name}" for name in existing_envs] + return Mock( + returncode=0, + stdout=f'{{"envs": {json.dumps(env_paths)}}}', + ) + elif "create" in cmd_str: + # Extract env name from command + if "--name" in cmd: + idx = cmd.index("--name") + 1 + existing_envs[cmd[idx]] = True + return Mock(returncode=0, stdout="Environment created") + elif "remove" in cmd_str: + if "--name" in cmd: + idx = cmd.index("--name") + 1 + existing_envs.pop(cmd[idx], None) + return Mock(returncode=0, stdout="Environment removed") + elif "--version" in cmd_str: + # Return version based on which env is being queried + for ename, ver in test_cases: + conda_name = f"hatch_{ename}" + if conda_name in existing_envs: + # Check if the python path matches this env + if conda_name in cmd_str: + return Mock(returncode=0, stdout=f"Python {ver}.0") + # Default: return last created version + for ename, ver in reversed(test_cases): + if f"hatch_{ename}" in existing_envs: + return Mock(returncode=0, stdout=f"Python {ver}.0") + return Mock(returncode=0, stdout="Python 3.12.0") + return Mock(returncode=0, stdout="") + + mock_run.side_effect = subprocess_side_effect + created_envs = [] - + try: for env_name, python_version in test_cases: - # Skip if this Python version is not available try: - result = self.manager.create_python_environment(env_name, python_version=python_version) + result = self.manager.create_python_environment( + env_name, python_version=python_version + ) if result: created_envs.append(env_name) - + # Verify Python version - actual_version = self.manager.get_python_version(env_name) + with patch("pathlib.Path.exists", return_value=True): + actual_version = self.manager.get_python_version(env_name) self.assertIsNotNone(actual_version) self.assertTrue( actual_version.startswith(python_version), - f"Expected Python {python_version}.x, got {actual_version}" + f"Expected Python {python_version}.x, got {actual_version}", ) except Exception as e: - # Log but don't fail test if specific Python version is not available print(f"Skipping Python {python_version} test: {e}") - + finally: # Cleanup for env_name in created_envs: @@ -676,12 +896,26 @@ def test_multiple_python_versions_real(self): pass # Best effort cleanup @integration_test(scope="system") - @slow_test - def test_error_handling_real(self): - """Test error handling with real operations.""" + @patch("subprocess.run") + def test_error_handling_real(self, mock_run): + """Test error handling with mocked subprocess for non-existent envs.""" + + # Mock: all env list calls return empty (no environments exist) + def subprocess_side_effect(cmd, *args, **kwargs): + cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd) + if ("env" in cmd_str and "list" in cmd_str) or ( + "info" in cmd_str and "--envs" in cmd_str + ): + return Mock(returncode=0, stdout='{"envs": []}') + return Mock(returncode=0, stdout="") + + mock_run.side_effect = subprocess_side_effect + # Test removing non-existent environment result = self.manager.remove_python_environment("nonexistent_env") - self.assertTrue(result) # Removing non existent environment returns True because it does nothing + self.assertTrue( + result + ) # Removing non existent environment returns True because it does nothing # Test getting info for non-existent environment info = self.manager.get_environment_info("nonexistent_env") @@ -714,7 +948,7 @@ def setUp(self): def tearDown(self): """Clean up test environment.""" # Clean up any conda/mamba environments created during this test - if hasattr(self, 'manager') and self.manager.is_available(): + if hasattr(self, "manager") and self.manager.is_available(): for env_name in self.created_environments: try: if self.manager.environment_exists(env_name): @@ -731,16 +965,19 @@ def _track_environment(self, env_name): self.created_environments.append(env_name) @regression_test - @patch('subprocess.run') + @patch("subprocess.run") def test_launch_shell_with_command(self, mock_run): """Test launching shell with specific command.""" env_name = "test_shell_env" cmd = "print('Hello from Python')" # Mock environment existence and Python executable - with patch.object(self.manager, 'environment_exists', return_value=True), \ - patch.object(self.manager, 'get_python_executable', return_value="/path/to/python"): - + with ( + patch.object(self.manager, "environment_exists", return_value=True), + patch.object( + self.manager, "get_python_executable", return_value="/path/to/python" + ), + ): mock_run.return_value = Mock(returncode=0) result = self.manager.launch_shell(env_name, cmd) @@ -754,17 +991,20 @@ def test_launch_shell_with_command(self, mock_run): self.assertIn(cmd, call_args) @regression_test - @patch('subprocess.run') - @patch('platform.system') + @patch("subprocess.run") + @patch("platform.system") def test_launch_shell_interactive_windows(self, mock_platform, mock_run): """Test launching interactive shell on Windows.""" mock_platform.return_value = "Windows" env_name = "test_shell_env" # Mock environment existence and Python executable - with patch.object(self.manager, 'environment_exists', return_value=True), \ - patch.object(self.manager, 'get_python_executable', return_value="/path/to/python"): - + with ( + patch.object(self.manager, "environment_exists", return_value=True), + patch.object( + self.manager, "get_python_executable", return_value="/path/to/python" + ), + ): mock_run.return_value = Mock(returncode=0) result = self.manager.launch_shell(env_name) @@ -777,17 +1017,20 @@ def test_launch_shell_interactive_windows(self, mock_platform, mock_run): self.assertIn("/c", call_args) @regression_test - @patch('subprocess.run') - @patch('platform.system') + @patch("subprocess.run") + @patch("platform.system") def test_launch_shell_interactive_unix(self, mock_platform, mock_run): """Test launching interactive shell on Unix.""" mock_platform.return_value = "Linux" env_name = "test_shell_env" # Mock environment existence and Python executable - with patch.object(self.manager, 'environment_exists', return_value=True), \ - patch.object(self.manager, 'get_python_executable', return_value="/path/to/python"): - + with ( + patch.object(self.manager, "environment_exists", return_value=True), + patch.object( + self.manager, "get_python_executable", return_value="/path/to/python" + ), + ): mock_run.return_value = Mock(returncode=0) result = self.manager.launch_shell(env_name) @@ -803,7 +1046,7 @@ def test_launch_shell_nonexistent_environment(self): """Test launching shell for non-existent environment.""" env_name = "nonexistent_env" - with patch.object(self.manager, 'environment_exists', return_value=False): + with patch.object(self.manager, "environment_exists", return_value=False): result = self.manager.launch_shell(env_name) self.assertFalse(result) @@ -812,9 +1055,10 @@ def test_launch_shell_no_python_executable(self): """Test launching shell when Python executable is not found.""" env_name = "test_shell_env" - with patch.object(self.manager, 'environment_exists', return_value=True), \ - patch.object(self.manager, 'get_python_executable', return_value=None): - + with ( + patch.object(self.manager, "environment_exists", return_value=True), + patch.object(self.manager, "get_python_executable", return_value=None), + ): result = self.manager.launch_shell(env_name) self.assertFalse(result) @@ -825,8 +1069,12 @@ def test_get_manager_info_structure(self): # Verify required fields are present required_fields = [ - "conda_executable", "mamba_executable", "preferred_manager", - "is_available", "platform", "python_version" + "conda_executable", + "mamba_executable", + "preferred_manager", + "is_available", + "platform", + "python_version", ] for field in required_fields: @@ -845,8 +1093,12 @@ def test_environment_diagnostics_structure(self): # Verify required fields are present required_fields = [ - "environment_name", "conda_env_name", "exists", "conda_available", - "manager_executable", "platform" + "environment_name", + "conda_env_name", + "exists", + "conda_available", + "manager_executable", + "platform", ] for field in required_fields: @@ -865,9 +1117,15 @@ def test_manager_diagnostics_structure(self): # Verify required fields are present required_fields = [ - "conda_executable", "mamba_executable", "conda_available", "mamba_available", - "any_manager_available", "preferred_manager", "platform", "python_version", - "environments_dir" + "conda_executable", + "mamba_executable", + "conda_available", + "mamba_available", + "any_manager_available", + "preferred_manager", + "platform", + "python_version", + "environments_dir", ] for field in required_fields: diff --git a/tests/test_python_installer.py b/tests/test_python_installer.py index b613b63..dc2fc54 100644 --- a/tests/test_python_installer.py +++ b/tests/test_python_installer.py @@ -7,14 +7,20 @@ from unittest import mock # Import wobble decorators for test categorization -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test, integration_test from hatch.installers.python_installer import PythonInstaller -from hatch.installers.installation_context import InstallationContext, InstallationStatus +from hatch.installers.installation_context import ( + InstallationContext, + InstallationStatus, +) from hatch.installers.installer_base import InstallationError + class DummyContext(InstallationContext): - def __init__(self, env_path=None, env_name=None, simulation_mode=False, extra_config=None): + def __init__( + self, env_path=None, env_name=None, simulation_mode=False, extra_config=None + ): self.simulation_mode = simulation_mode self.extra_config = extra_config or {} self.environment_path = env_path @@ -23,12 +29,13 @@ def __init__(self, env_path=None, env_name=None, simulation_mode=False, extra_co def get_config(self, key, default=None): return self.extra_config.get(key, default) + class TestPythonInstaller(unittest.TestCase): """Tests for the PythonInstaller class covering validation, installation, and error handling.""" def setUp(self): """Set up a temporary directory and PythonInstaller instance for each test.""" - + self.temp_dir = tempfile.mkdtemp() self.env_path = Path(self.temp_dir) / "test_env" @@ -37,11 +44,13 @@ def setUp(self): # assert the virtual environment was created successfully self.assertTrue(self.env_path.exists() and self.env_path.is_dir()) - + self.installer = PythonInstaller() - self.dummy_context = DummyContext(self.env_path, env_name="test_env", extra_config={ - "target_dir": str(self.env_path) - }) + self.dummy_context = DummyContext( + self.env_path, + env_name="test_env", + extra_config={"target_dir": str(self.env_path)}, + ) def tearDown(self): """Clean up the temporary directory after each test.""" @@ -62,7 +71,11 @@ def test_validate_dependency_invalid_missing_fields(self): @regression_test def test_validate_dependency_invalid_package_manager(self): """Test validate_dependency returns False for unsupported package manager.""" - dep = {"name": "requests", "version_constraint": ">=2.0.0", "package_manager": "unknown"} + dep = { + "name": "requests", + "version_constraint": ">=2.0.0", + "package_manager": "unknown", + } self.assertFalse(self.installer.validate_dependency(dep)) @regression_test @@ -78,7 +91,10 @@ def test_can_install_wrong_type(self): self.assertFalse(self.installer.can_install(dep)) @regression_test - @mock.patch("hatch.installers.python_installer.subprocess.Popen", side_effect=Exception("fail")) + @mock.patch( + "hatch.installers.python_installer.subprocess.Popen", + side_effect=Exception("fail"), + ) def test_run_pip_subprocess_exception(self, mock_popen): """Test _run_pip_subprocess raises InstallationError on exception.""" cmd = [sys.executable, "-m", "pip", "--version"] @@ -106,7 +122,10 @@ def test_install_success(self, mock_run): @mock.patch.object(PythonInstaller, "_run_pip_subprocess", return_value=1) def test_install_failure(self, mock_run): """Test install raises InstallationError on pip failure.""" - dep = {"name": "requests", "version_constraint": ">=2.0.0"} # The content don't matter here given the mock + dep = { + "name": "requests", + "version_constraint": ">=2.0.0", + } # The content don't matter here given the mock context = DummyContext() with self.assertRaises(InstallationError): self.installer.install(dep, context) @@ -129,199 +148,180 @@ def test_uninstall_failure(self, mock_run): with self.assertRaises(InstallationError): self.installer.uninstall(dep, context) -class TestPythonInstallerIntegration(unittest.TestCase): +class TestPythonInstallerIntegration(unittest.TestCase): """Integration tests for PythonInstaller that perform actual package installations.""" + @classmethod + def setUpClass(cls): + """Create a shared virtual environment once for all integration tests.""" + cls.shared_temp_dir = tempfile.mkdtemp() + cls.shared_env_path = Path(cls.shared_temp_dir) / "shared_test_env" + subprocess.check_call([sys.executable, "-m", "venv", str(cls.shared_env_path)]) + if sys.platform == "win32": + cls.shared_python_executable = ( + cls.shared_env_path / "Scripts" / "python.exe" + ) + else: + cls.shared_python_executable = cls.shared_env_path / "bin" / "python" + + @classmethod + def tearDownClass(cls): + """Remove the shared virtual environment.""" + shutil.rmtree(cls.shared_temp_dir, ignore_errors=True) + def setUp(self): - """Set up a temporary directory and PythonInstaller instance for each test.""" - + """Set up a PythonInstaller instance for each test. + + Mocked tests use a simple temp directory (no real venv needed). + Integration tests use the shared venv from setUpClass. + """ self.temp_dir = tempfile.mkdtemp() self.env_path = Path(self.temp_dir) / "test_env" - - # Use pip to create a virtual environment - subprocess.check_call([sys.executable, "-m", "venv", str(self.env_path)]) - - # assert the virtual environment was created successfully - self.assertTrue(self.env_path.exists() and self.env_path.is_dir()) + self.env_path.mkdir(parents=True, exist_ok=True) - # Get the Python executable in the virtual environment - if sys.platform == "win32": - self.python_executable = self.env_path / "Scripts" / "python.exe" - else: - self.python_executable = self.env_path / "bin" / "python" - self.installer = PythonInstaller() - self.dummy_context = DummyContext(self.env_path, env_name="test_env", extra_config={ - "python_executable": self.python_executable, - "target_dir": str(self.env_path) - }) + self.dummy_context = DummyContext( + self.env_path, + env_name="test_env", + extra_config={ + "python_executable": sys.executable, + "target_dir": str(self.env_path), + }, + ) def tearDown(self): """Clean up the temporary directory after each test.""" shutil.rmtree(self.temp_dir) - @integration_test(scope="component") - @slow_test - def test_install_actual_package_success(self): - """Test actual installation of a real Python package without mocking. - - Uses a lightweight package that's commonly available and installs quickly. - This validates the entire installation pipeline including subprocess handling. + @regression_test + @mock.patch.object(PythonInstaller, "_run_pip_subprocess", return_value=0) + def test_install_actual_package_success(self, mock_run): + """Test installation pipeline returns COMPLETED on successful pip install. + + Mocks _run_pip_subprocess to validate our install flow without calling pip. """ - # Use a lightweight, commonly available package for testing - dep = { - "name": "wheel", - "version_constraint": "*", - "type": "python" - } - - # Create a virtual environment context to avoid polluting system packages - context = DummyContext( - env_path=self.env_path, - env_name="test_env", - extra_config={ - "python_executable": self.python_executable, - "target_dir": str(self.env_path) - } - ) - result = self.installer.install(dep, context) + dep = {"name": "wheel", "version_constraint": "*", "type": "python"} + + result = self.installer.install(dep, self.dummy_context) self.assertEqual(result.status, InstallationStatus.COMPLETED) self.assertIn("wheel", result.dependency_name) + mock_run.assert_called_once() - @integration_test(scope="component") - @slow_test - def test_install_package_with_version_constraint(self): + @regression_test + @mock.patch.object(PythonInstaller, "_run_pip_subprocess", return_value=0) + def test_install_package_with_version_constraint(self, mock_run): """Test installation with specific version constraint. - Validates that version constraints are properly passed to pip - and that the installation succeeds with real package resolution. + Validates that version constraints are properly passed through + our install flow and result metadata is populated. """ dep = { "name": "setuptools", "version_constraint": ">=40.0.0", - "type": "python" + "type": "python", } - - context = DummyContext( - env_path=self.env_path, - env_name="test_env", - extra_config={ - "python_executable": self.python_executable - }) - result = self.installer.install(dep, context) + result = self.installer.install(dep, self.dummy_context) self.assertEqual(result.status, InstallationStatus.COMPLETED) - # Verify the dependency was processed correctly self.assertIsNotNone(result.metadata) + # Verify the version constraint was included in the command + cmd_args = mock_run.call_args[0][0] + self.assertTrue( + any("setuptools>=40.0.0" in arg for arg in cmd_args), + f"Expected 'setuptools>=40.0.0' in pip command args: {cmd_args}", + ) - @integration_test(scope="component") - @slow_test - def test_install_package_with_extras(self): + @regression_test + @mock.patch.object(PythonInstaller, "_run_pip_subprocess", return_value=0) + def test_install_package_with_extras(self, mock_run): """Test installation of a package with extras specification. - - Tests the extras handling functionality with a real package installation. + + Validates that extras are correctly formatted in the pip command. """ dep = { "name": "requests", "version_constraint": "*", "type": "python", - "extras": ["security"] # pip[security] if available + "extras": ["security"], } - - context = DummyContext( - env_path=self.env_path, - env_name="test_env", - extra_config={ - "python_executable": self.python_executable - }) - - result = self.installer.install(dep, context) + + result = self.installer.install(dep, self.dummy_context) self.assertEqual(result.status, InstallationStatus.COMPLETED) + # Verify extras were included in the pip command + cmd_args = mock_run.call_args[0][0] + self.assertTrue( + any("requests[security]" in arg for arg in cmd_args), + f"Expected 'requests[security]' in pip command args: {cmd_args}", + ) - @integration_test(scope="component") - @slow_test - def test_uninstall_actual_package(self): - """Test actual uninstallation of a Python package. - - First installs a package, then uninstalls it to test the complete cycle. - This validates both installation and uninstallation without mocking. + @regression_test + @mock.patch.object(PythonInstaller, "_run_pip_subprocess", return_value=0) + def test_uninstall_actual_package(self, mock_run): + """Test install/uninstall cycle completes successfully. + + Mocks _run_pip_subprocess to validate our install and uninstall flow. """ - dep = { - "name": "wheel", - "version_constraint": "*", - "type": "python" - } - - context = DummyContext( - env_path=self.env_path, - env_name="test_env", - extra_config={ - "python_executable": self.python_executable - }) - + dep = {"name": "wheel", "version_constraint": "*", "type": "python"} + # First install the package - install_result = self.installer.install(dep, context) + install_result = self.installer.install(dep, self.dummy_context) self.assertEqual(install_result.status, InstallationStatus.COMPLETED) - + # Then uninstall it - uninstall_result = self.installer.uninstall(dep, context) + uninstall_result = self.installer.uninstall(dep, self.dummy_context) self.assertEqual(uninstall_result.status, InstallationStatus.COMPLETED) - @integration_test(scope="component") - @slow_test - def test_install_nonexistent_package_failure(self): - """Test that installation fails appropriately for non-existent packages. - - This validates error handling when pip encounters a package that doesn't exist, - without using mocks to simulate the failure. + # Verify both install and uninstall called _run_pip_subprocess + self.assertEqual(mock_run.call_count, 2) + + @regression_test + @mock.patch.object(PythonInstaller, "_run_pip_subprocess", return_value=1) + def test_install_nonexistent_package_failure(self, mock_run): + """Test that installation fails appropriately when pip returns non-zero. + + Mocks _run_pip_subprocess to return failure, validating our error handling. """ dep = { "name": "this-package-definitely-does-not-exist-12345", "version_constraint": "*", - "type": "python" + "type": "python", } - - context = DummyContext( - env_path=self.env_path, - env_name="test_env", - extra_config={ - "python_executable": self.python_executable - }) - + with self.assertRaises(InstallationError) as cm: - self.installer.install(dep, context) - + self.installer.install(dep, self.dummy_context) + # Verify the error contains useful information error_msg = str(cm.exception) self.assertIn("this-package-definitely-does-not-exist-12345", error_msg) @integration_test(scope="component") - @slow_test def test_get_installation_info_for_installed_package(self): """Test retrieval of installation info for an actually installed package. - - This tests the get_installation_info method with a real package - that should be available in most Python environments. + + Uses the shared venv from setUpClass. This tests the get_installation_info + method with a real package that should be available in the shared venv. """ dep = { - "name": "pip", # pip should be available in most environments + "name": "pip", # pip should be available in the shared venv "version_constraint": "*", - "type": "python" + "type": "python", } - + context = DummyContext( - env_path=self.env_path, - env_name="test_env", + env_path=self.__class__.shared_env_path, + env_name="shared_test_env", extra_config={ - "python_executable": self.python_executable - }) - + "python_executable": self.__class__.shared_python_executable, + }, + ) + info = self.installer.get_installation_info(dep, context) self.assertIsInstance(info, dict) # Basic checks for expected info structure - if info: # Only check if info was returned (some implementations might return empty dict) + if info: self.assertIn("dependency_name", info) + if __name__ == "__main__": unittest.main() diff --git a/tests/test_registry.py b/tests/test_registry.py index f0dc070..3c85a1d 100644 --- a/tests/test_registry.py +++ b/tests/test_registry.py @@ -4,30 +4,31 @@ retrieved from the registry. """ -import sys -from pathlib import Path import unittest -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test # Import path management removed - using test_data_utils for test dependencies # It is mandatory to import the installer classes to ensure they are registered -from hatch.installers.hatch_installer import HatchInstaller -from hatch.installers.python_installer import PythonInstaller -from hatch.installers.system_installer import SystemInstaller -from hatch.installers.docker_installer import DockerInstaller from hatch.installers import installer_registry, DependencyInstaller + class TestInstallerRegistry(unittest.TestCase): """Test suite for the installer registry.""" + @regression_test def test_registered_types(self): """Test that all expected installer types are registered.""" registered_types = installer_registry.get_registered_types() expected_types = ["hatch", "python", "system", "docker"] for expected_type in expected_types: - self.assertIn(expected_type, registered_types, f"{expected_type} installer should be registered") + self.assertIn( + expected_type, + registered_types, + f"{expected_type} installer should be registered", + ) + @regression_test def test_get_installer_instance(self): """Test that the registry returns a valid installer instance for each type.""" @@ -35,11 +36,13 @@ def test_get_installer_instance(self): installer = installer_registry.get_installer(dep_type) self.assertIsInstance(installer, DependencyInstaller) self.assertEqual(installer.installer_type, dep_type) + @regression_test def test_error_on_unknown_type(self): """Test that requesting an unknown type raises ValueError.""" with self.assertRaises(ValueError): installer_registry.get_installer("unknown_type") + @regression_test def test_registry_repr_and_len(self): """Test __repr__ and __len__ methods for coverage.""" @@ -47,5 +50,6 @@ def test_registry_repr_and_len(self): self.assertIn("InstallerRegistry", repr_str) self.assertGreaterEqual(len(installer_registry), 4) + if __name__ == "__main__": unittest.main() diff --git a/tests/test_registry_retriever.py b/tests/test_registry_retriever.py index 8965917..cd92037 100644 --- a/tests/test_registry_retriever.py +++ b/tests/test_registry_retriever.py @@ -1,14 +1,11 @@ -import sys import unittest import tempfile import shutil import logging -import json import datetime -import os from pathlib import Path -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test, integration_test # Import path management removed - using test_data_utils for test dependencies @@ -16,11 +13,11 @@ # Configure logging logging.basicConfig( - level=logging.DEBUG, - format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' + level=logging.DEBUG, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s" ) logger = logging.getLogger("hatch.registry_tests") + class RegistryRetrieverTests(unittest.TestCase): """Tests for Registry Retriever functionality.""" @@ -30,29 +27,38 @@ def setUp(self): self.temp_dir = tempfile.mkdtemp() self.cache_dir = Path(self.temp_dir) / "cache" self.cache_dir.mkdir(parents=True, exist_ok=True) - + # Path to the registry file (using the one in project data) - for fallback/reference only - self.registry_path = Path(__file__).parent.parent.parent / "data" / "hatch_packages_registry.json" + self.registry_path = ( + Path(__file__).parent.parent.parent + / "data" + / "hatch_packages_registry.json" + ) if not self.registry_path.exists(): # Try alternate location - self.registry_path = Path(__file__).parent.parent.parent / "Hatch-Registry" / "data" / "hatch_packages_registry.json" - + self.registry_path = ( + Path(__file__).parent.parent.parent + / "Hatch-Registry" + / "data" + / "hatch_packages_registry.json" + ) + # We're testing online mode, but keep a local copy for comparison and backup self.local_registry_path = Path(self.temp_dir) / "hatch_packages_registry.json" if self.registry_path.exists(): shutil.copy(self.registry_path, self.local_registry_path) - + def tearDown(self): """Clean up test environment after each test.""" # Remove temporary directory shutil.rmtree(self.temp_dir) + @regression_test def test_registry_init(self): """Test initialization of registry retriever.""" # Test initialization in online mode (primary test focus) online_retriever = RegistryRetriever( - local_cache_dir=self.cache_dir, - simulation_mode=False + local_cache_dir=self.cache_dir, simulation_mode=False ) # Verify URL format for online mode @@ -62,14 +68,14 @@ def test_registry_init(self): # Verify cache path is set correctly self.assertEqual( online_retriever.registry_cache_path, - self.cache_dir / "registry" / "hatch_packages_registry.json" + self.cache_dir / "registry" / "hatch_packages_registry.json", ) # Also test initialization with local file in simulation mode (for reference) sim_retriever = RegistryRetriever( local_cache_dir=self.cache_dir, simulation_mode=True, - local_registry_cache_path=self.local_registry_path + local_registry_cache_path=self.local_registry_path, ) # Verify registry cache path is set correctly in simulation mode @@ -81,8 +87,7 @@ def test_registry_cache_management(self): """Test registry cache management.""" # Initialize retriever with a short TTL in online mode retriever = RegistryRetriever( - cache_ttl=5, # 5 seconds TTL - local_cache_dir=self.cache_dir + cache_ttl=5, local_cache_dir=self.cache_dir # 5 seconds TTL ) # Get registry data (first fetch from online) @@ -91,42 +96,48 @@ def test_registry_cache_management(self): # Verify in-memory cache works (should not read from disk) registry_data2 = retriever.get_registry() - self.assertIs(registry_data1, registry_data2) # Should be the same object in memory + self.assertIs( + registry_data1, registry_data2 + ) # Should be the same object in memory # Force refresh and verify it gets loaded again (potentially from online) registry_data3 = retriever.get_registry(force_refresh=True) self.assertIsNotNone(registry_data3) # Verify the cache file was created - self.assertTrue(retriever.registry_cache_path.exists(), "Cache file was not created") + self.assertTrue( + retriever.registry_cache_path.exists(), "Cache file was not created" + ) # Modify the persistent timestamp to test cache invalidation # We need to manipulate the persistent timestamp file, not just the cache file mtime timestamp_file = retriever._last_fetch_time_path if timestamp_file.exists(): # Write an old timestamp to the persistent timestamp file - yesterday = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=1) - old_timestamp_str = yesterday.isoformat().replace('+00:00', 'Z') - with open(timestamp_file, 'w', encoding='utf-8') as f: + yesterday = datetime.datetime.now( + datetime.timezone.utc + ) - datetime.timedelta(days=1) + old_timestamp_str = yesterday.isoformat().replace("+00:00", "Z") + with open(timestamp_file, "w", encoding="utf-8") as f: f.write(old_timestamp_str) # Reload the timestamp from file retriever._load_last_fetch_time() - + # Check if cache is outdated - should be since we modified the persistent timestamp self.assertTrue(retriever.is_cache_outdated()) - + # Force refresh and verify new data is loaded (should fetch from online) registry_data4 = retriever.get_registry(force_refresh=True) self.assertIsNotNone(registry_data4) self.assertIn("repositories", registry_data4) self.assertIn("last_updated", registry_data4) + @integration_test(scope="service") def test_online_mode(self): """Test registry retriever in online mode.""" # Initialize in online mode retriever = RegistryRetriever( - local_cache_dir=self.cache_dir, - simulation_mode=False + local_cache_dir=self.cache_dir, simulation_mode=False ) # Get registry and verify it contains expected data @@ -136,7 +147,11 @@ def test_online_mode(self): # Verify registry structure self.assertIsInstance(registry.get("repositories"), list) - self.assertGreater(len(registry.get("repositories", [])), 0, "Registry should contain repositories") + self.assertGreater( + len(registry.get("repositories", [])), + 0, + "Registry should contain repositories", + ) # Get registry again with force refresh (should fetch from online) registry2 = retriever.get_registry(force_refresh=True) @@ -144,12 +159,14 @@ def test_online_mode(self): # Test error handling with an existing cache # First ensure we have a valid cache file - self.assertTrue(retriever.registry_cache_path.exists(), "Cache file should exist after previous calls") + self.assertTrue( + retriever.registry_cache_path.exists(), + "Cache file should exist after previous calls", + ) # Create a new retriever with invalid URL but using the same cache bad_retriever = RegistryRetriever( - local_cache_dir=self.cache_dir, - simulation_mode=False + local_cache_dir=self.cache_dir, simulation_mode=False ) # Mock the URL to be invalid bad_retriever.registry_url = "https://nonexistent.example.com/registry.json" @@ -163,7 +180,7 @@ def test_online_mode(self): bad_retriever.get_registry(force_refresh=True) except Exception: pass # Expected to fail, that's OK - + @regression_test def test_persistent_timestamp_across_cli_invocations(self): """Test that persistent timestamp works across separate CLI invocations.""" @@ -171,7 +188,7 @@ def test_persistent_timestamp_across_cli_invocations(self): retriever1 = RegistryRetriever( cache_ttl=300, # 5 minutes TTL local_cache_dir=self.cache_dir, - simulation_mode=False + simulation_mode=False, ) # Get registry (should fetch from online) @@ -179,7 +196,10 @@ def test_persistent_timestamp_across_cli_invocations(self): self.assertIsNotNone(registry1) # Verify timestamp file was created - self.assertTrue(retriever1._last_fetch_time_path.exists(), "Timestamp file should be created") + self.assertTrue( + retriever1._last_fetch_time_path.exists(), + "Timestamp file should be created", + ) # Get the timestamp from the first fetch first_fetch_time = retriever1._last_fetch_time @@ -189,11 +209,13 @@ def test_persistent_timestamp_across_cli_invocations(self): retriever2 = RegistryRetriever( cache_ttl=300, # 5 minutes TTL local_cache_dir=self.cache_dir, - simulation_mode=False + simulation_mode=False, ) # Verify the timestamp was loaded from disk - self.assertGreater(retriever2._last_fetch_time, 0, "Timestamp should be loaded from disk") + self.assertGreater( + retriever2._last_fetch_time, 0, "Timestamp should be loaded from disk" + ) # Get registry (should use cache since timestamp is recent) registry2 = retriever2.get_registry() @@ -209,7 +231,7 @@ def test_persistent_timestamp_edge_cases(self): retriever = RegistryRetriever( cache_ttl=300, # 5 minutes TTL local_cache_dir=self.cache_dir, - simulation_mode=False + simulation_mode=False, ) # Test 1: Corrupt timestamp file @@ -217,34 +239,51 @@ def test_persistent_timestamp_edge_cases(self): timestamp_file.parent.mkdir(parents=True, exist_ok=True) # Write corrupt data to timestamp file - with open(timestamp_file, 'w', encoding='utf-8') as f: + with open(timestamp_file, "w", encoding="utf-8") as f: f.write("invalid_timestamp_data") # Should handle gracefully and treat as no timestamp retriever._load_last_fetch_time() - self.assertEqual(retriever._last_fetch_time, 0, "Corrupt timestamp should be treated as no timestamp") + self.assertEqual( + retriever._last_fetch_time, + 0, + "Corrupt timestamp should be treated as no timestamp", + ) # Test 2: Future timestamp (clock skew scenario) - future_time = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=1) - future_timestamp_str = future_time.isoformat().replace('+00:00', 'Z') - with open(timestamp_file, 'w', encoding='utf-8') as f: + future_time = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta( + hours=1 + ) + future_timestamp_str = future_time.isoformat().replace("+00:00", "Z") + with open(timestamp_file, "w", encoding="utf-8") as f: f.write(future_timestamp_str) - + retriever._load_last_fetch_time() # Should handle future timestamps gracefully (treat as valid but check TTL normally) - self.assertGreater(retriever._last_fetch_time, 0, "Future timestamp should be loaded") - + self.assertGreater( + retriever._last_fetch_time, 0, "Future timestamp should be loaded" + ) + # Test 3: Empty timestamp file - with open(timestamp_file, 'w', encoding='utf-8') as f: + with open(timestamp_file, "w", encoding="utf-8") as f: f.write("") - + retriever._load_last_fetch_time() - self.assertEqual(retriever._last_fetch_time, 0, "Empty timestamp file should be treated as no timestamp") - + self.assertEqual( + retriever._last_fetch_time, + 0, + "Empty timestamp file should be treated as no timestamp", + ) + # Test 4: Missing timestamp file timestamp_file.unlink() retriever._load_last_fetch_time() - self.assertEqual(retriever._last_fetch_time, 0, "Missing timestamp file should be treated as no timestamp") + self.assertEqual( + retriever._last_fetch_time, + 0, + "Missing timestamp file should be treated as no timestamp", + ) + if __name__ == "__main__": unittest.main() diff --git a/tests/test_system_installer.py b/tests/test_system_installer.py index e2b48e1..8ae7a82 100644 --- a/tests/test_system_installer.py +++ b/tests/test_system_installer.py @@ -10,17 +10,22 @@ import sys from pathlib import Path from unittest.mock import patch, MagicMock -from typing import Dict, Any -from wobble.decorators import regression_test, integration_test, slow_test +from wobble.decorators import regression_test, integration_test from hatch.installers.system_installer import SystemInstaller from hatch.installers.installer_base import InstallationError -from hatch.installers.installation_context import InstallationContext, InstallationResult, InstallationStatus +from hatch.installers.installation_context import ( + InstallationContext, + InstallationResult, + InstallationStatus, +) class DummyContext(InstallationContext): - def __init__(self, env_path=None, env_name=None, simulation_mode=False, extra_config=None): + def __init__( + self, env_path=None, env_name=None, simulation_mode=False, extra_config=None + ): self.simulation_mode = simulation_mode self.extra_config = extra_config or {} self.environment_path = env_path @@ -39,7 +44,7 @@ def setUp(self): env_path=Path("/test/env"), env_name="test_env", simulation_mode=False, - extra_config={} + extra_config={}, ) @regression_test @@ -56,11 +61,13 @@ def test_can_install_valid_dependency(self): "type": "system", "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } - - with patch.object(self.installer, '_is_platform_supported', return_value=True), \ - patch.object(self.installer, '_is_apt_available', return_value=True): + + with ( + patch.object(self.installer, "_is_platform_supported", return_value=True), + patch.object(self.installer, "_is_apt_available", return_value=True), + ): self.assertTrue(self.installer.can_install(dependency)) @regression_test @@ -68,7 +75,7 @@ def test_can_install_wrong_type(self): dependency = { "type": "python", "name": "requests", - "version_constraint": ">=2.0.0" + "version_constraint": ">=2.0.0", } self.assertFalse(self.installer.can_install(dependency)) @@ -79,10 +86,10 @@ def test_can_install_unsupported_platform(self): "type": "system", "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } - with patch.object(self.installer, '_is_platform_supported', return_value=False): + with patch.object(self.installer, "_is_platform_supported", return_value=False): self.assertFalse(self.installer.can_install(dependency)) @regression_test @@ -91,11 +98,13 @@ def test_can_install_apt_not_available(self): "type": "system", "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } - with patch.object(self.installer, '_is_platform_supported', return_value=True), \ - patch.object(self.installer, '_is_apt_available', return_value=False): + with ( + patch.object(self.installer, "_is_platform_supported", return_value=True), + patch.object(self.installer, "_is_apt_available", return_value=False), + ): self.assertFalse(self.installer.can_install(dependency)) @regression_test @@ -103,26 +112,20 @@ def test_validate_dependency_valid(self): dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } self.assertTrue(self.installer.validate_dependency(dependency)) @regression_test def test_validate_dependency_missing_name(self): - dependency = { - "version_constraint": ">=7.0.0", - "package_manager": "apt" - } - + dependency = {"version_constraint": ">=7.0.0", "package_manager": "apt"} + self.assertFalse(self.installer.validate_dependency(dependency)) @regression_test def test_validate_dependency_missing_version_constraint(self): - dependency = { - "name": "curl", - "package_manager": "apt" - } + dependency = {"name": "curl", "package_manager": "apt"} self.assertFalse(self.installer.validate_dependency(dependency)) @@ -131,7 +134,7 @@ def test_validate_dependency_invalid_package_manager(self): dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "yum" + "package_manager": "yum", } self.assertFalse(self.installer.validate_dependency(dependency)) @@ -141,14 +144,14 @@ def test_validate_dependency_invalid_version_constraint(self): dependency = { "name": "curl", "version_constraint": "invalid_version", - "package_manager": "apt" + "package_manager": "apt", } self.assertFalse(self.installer.validate_dependency(dependency)) @regression_test - @patch('platform.system') - @patch('pathlib.Path.exists') + @patch("platform.system") + @patch("pathlib.Path.exists") def test_is_platform_supported_debian(self, mock_exists, mock_system): """Test platform support detection for Debian.""" mock_system.return_value = "Linux" @@ -158,9 +161,9 @@ def test_is_platform_supported_debian(self, mock_exists, mock_system): mock_exists.assert_called_with() @regression_test - @patch('platform.system') - @patch('pathlib.Path.exists') - @patch('builtins.open') + @patch("platform.system") + @patch("pathlib.Path.exists") + @patch("builtins.open") def test_is_platform_supported_ubuntu(self, mock_open, mock_exists, mock_system): """Test platform support detection for Ubuntu.""" mock_system.return_value = "Linux" @@ -168,14 +171,14 @@ def test_is_platform_supported_ubuntu(self, mock_open, mock_exists, mock_system) # Mock os-release file content mock_file = MagicMock() - mock_file.read.return_value = "NAME=\"Ubuntu\"\nVERSION=\"20.04\"" + mock_file.read.return_value = 'NAME="Ubuntu"\nVERSION="20.04"' mock_open.return_value.__enter__.return_value = mock_file self.assertTrue(self.installer._is_platform_supported()) @regression_test - @patch('platform.system') - @patch('pathlib.Path.exists') + @patch("platform.system") + @patch("pathlib.Path.exists") def test_is_platform_supported_unsupported(self, mock_exists, mock_system): """Test platform support detection for unsupported systems.""" mock_system.return_value = "Windows" @@ -184,7 +187,7 @@ def test_is_platform_supported_unsupported(self, mock_exists, mock_system): self.assertFalse(self.installer._is_platform_supported()) @regression_test - @patch('shutil.which') + @patch("shutil.which") def test_is_apt_available_true(self, mock_which): """Test apt availability detection when apt is available.""" mock_which.return_value = "/usr/bin/apt" @@ -193,7 +196,7 @@ def test_is_apt_available_true(self, mock_which): mock_which.assert_called_once_with("apt") @regression_test - @patch('shutil.which') + @patch("shutil.which") def test_is_apt_available_false(self, mock_which): """Test apt availability detection when apt is not available.""" mock_which.return_value = None @@ -206,7 +209,7 @@ def test_build_apt_command_basic(self): dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } command = self.installer._build_apt_command(dependency, self.mock_context) @@ -218,7 +221,7 @@ def test_build_apt_command_exact_version(self): dependency = { "name": "curl", "version_constraint": "==7.68.0", - "package_manager": "apt" + "package_manager": "apt", } command = self.installer._build_apt_command(dependency, self.mock_context) @@ -230,7 +233,7 @@ def test_build_apt_command_automated(self): dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } self.mock_context.extra_config = {"automated": True} @@ -238,22 +241,27 @@ def test_build_apt_command_automated(self): self.assertEqual(command, ["sudo", "apt", "install", "-y", "curl"]) @regression_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") - @patch('subprocess.run') + @unittest.skipIf( + sys.platform.startswith("win"), "System dependency test skipped on Windows" + ) + @patch("subprocess.run") def test_verify_installation_success(self, mock_run): """Test successful installation verification.""" mock_run.return_value = subprocess.CompletedProcess( args=["apt-cache", "policy", "curl"], returncode=0, stdout="curl:\n Installed: 7.68.0-1ubuntu2.7\n Candidate: 7.68.0-1ubuntu2.7\n Version table:\n *** 7.68.0-1ubuntu2.7 500\n 500 http://archive.ubuntu.com/ubuntu focal-updates/main amd64 Packages\n 100 /var/lib/dpkg/status", - stderr="" + stderr="", ) version = self.installer._verify_installation("curl") - self.assertTrue(isinstance(version, str) and len(version) > 0, f"Expected a non-empty version string, got: {version}") + self.assertTrue( + isinstance(version, str) and len(version) > 0, + f"Expected a non-empty version string, got: {version}", + ) @regression_test - @patch('subprocess.run') + @patch("subprocess.run") def test_verify_installation_failure(self, mock_run): """Test installation verification when package not found.""" mock_run.side_effect = subprocess.CalledProcessError(1, ["dpkg-query"]) @@ -265,14 +273,15 @@ def test_verify_installation_failure(self, mock_run): def test_parse_apt_error_permission_denied(self): """Test parsing permission denied error.""" error = subprocess.CalledProcessError( - 1, ["apt", "install", "curl"], - stderr="E: Could not open lock file - permission denied" + 1, + ["apt", "install", "curl"], + stderr="E: Could not open lock file - permission denied", ) wrapped_error = InstallationError( str(error.stderr), dependency_name="curl", error_code="APT_INSTALL_FAILED", - cause=error + cause=error, ) message = self.installer._parse_apt_error(wrapped_error) self.assertIn("permission denied", message.lower()) @@ -282,14 +291,15 @@ def test_parse_apt_error_permission_denied(self): def test_parse_apt_error_package_not_found(self): """Test parsing package not found error.""" error = subprocess.CalledProcessError( - 100, ["apt", "install", "nonexistent"], - stderr="E: Unable to locate package nonexistent" + 100, + ["apt", "install", "nonexistent"], + stderr="E: Unable to locate package nonexistent", ) wrapped_error = InstallationError( str(error.stderr), dependency_name="nonexistent", error_code="APT_INSTALL_FAILED", - cause=error + cause=error, ) message = self.installer._parse_apt_error(wrapped_error) self.assertIn("package not found", message.lower()) @@ -299,25 +309,26 @@ def test_parse_apt_error_package_not_found(self): def test_parse_apt_error_generic(self): """Test parsing generic apt error.""" error = subprocess.CalledProcessError( - 1, ["apt", "install", "curl"], - stderr="Some unknown error occurred" + 1, ["apt", "install", "curl"], stderr="Some unknown error occurred" ) wrapped_error = InstallationError( str(error.stderr), dependency_name="curl", error_code="APT_INSTALL_FAILED", - cause=error + cause=error, ) message = self.installer._parse_apt_error(wrapped_error) self.assertIn("apt command failed", message.lower()) self.assertIn("unknown error", message.lower()) @regression_test - @patch.object(SystemInstaller, 'validate_dependency') - @patch.object(SystemInstaller, '_build_apt_command') - @patch.object(SystemInstaller, '_run_apt_subprocess') - @patch.object(SystemInstaller, '_verify_installation') - def test_install_success(self, mock_verify, mock_execute, mock_build, mock_validate): + @patch.object(SystemInstaller, "validate_dependency") + @patch.object(SystemInstaller, "_build_apt_command") + @patch.object(SystemInstaller, "_run_apt_subprocess") + @patch.object(SystemInstaller, "_verify_installation") + def test_install_success( + self, mock_verify, mock_execute, mock_build, mock_validate + ): """Test successful installation.""" # Setup mocks mock_validate.return_value = True @@ -328,15 +339,18 @@ def test_install_success(self, mock_verify, mock_execute, mock_build, mock_valid dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } # Test with progress callback progress_calls = [] + def progress_callback(operation, progress, message): progress_calls.append((operation, progress, message)) - result = self.installer.install(dependency, self.mock_context, progress_callback) + result = self.installer.install( + dependency, self.mock_context, progress_callback + ) # Verify result self.assertEqual(result.dependency_name, "curl") @@ -350,15 +364,12 @@ def progress_callback(operation, progress, message): self.assertEqual(progress_calls[-1][1], 100.0) # Complete @regression_test - @patch.object(SystemInstaller, 'validate_dependency') + @patch.object(SystemInstaller, "validate_dependency") def test_install_invalid_dependency(self, mock_validate): """Test installation with invalid dependency.""" mock_validate.return_value = False - dependency = { - "name": "curl", - "version_constraint": "invalid" - } + dependency = {"name": "curl", "version_constraint": "invalid"} with self.assertRaises(InstallationError) as exc_info: self.installer.install(dependency, self.mock_context) @@ -367,9 +378,9 @@ def test_install_invalid_dependency(self, mock_validate): self.assertIn("Invalid dependency", str(exc_info.exception)) @regression_test - @patch.object(SystemInstaller, 'validate_dependency') - @patch.object(SystemInstaller, '_build_apt_command') - @patch.object(SystemInstaller, '_run_apt_subprocess') + @patch.object(SystemInstaller, "validate_dependency") + @patch.object(SystemInstaller, "_build_apt_command") + @patch.object(SystemInstaller, "_run_apt_subprocess") def test_install_apt_failure(self, mock_execute, mock_build, mock_validate): """Test installation failure due to apt command error.""" mock_validate.return_value = True @@ -380,7 +391,7 @@ def test_install_apt_failure(self, mock_execute, mock_build, mock_validate): dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } with self.assertRaises(InstallationError) as exc_info: @@ -398,34 +409,36 @@ def test_install_apt_failure(self, mock_execute, mock_build, mock_validate): self.assertEqual(exc_info2.exception.dependency_name, "curl") @regression_test - @patch.object(SystemInstaller, 'validate_dependency') - @patch.object(SystemInstaller, '_simulate_installation') + @patch.object(SystemInstaller, "validate_dependency") + @patch.object(SystemInstaller, "_simulate_installation") def test_install_simulation_mode(self, mock_simulate, mock_validate): """Test installation in simulation mode.""" mock_validate.return_value = True mock_simulate.return_value = InstallationResult( dependency_name="curl", status=InstallationStatus.COMPLETED, - metadata={"simulation": True} + metadata={"simulation": True}, ) self.mock_context.simulation_mode = True dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } - + result = self.installer.install(dependency, self.mock_context) - + self.assertEqual(result.dependency_name, "curl") self.assertEqual(result.status, InstallationStatus.COMPLETED) self.assertTrue(result.metadata["simulation"]) mock_simulate.assert_called_once() @regression_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") - @patch.object(SystemInstaller, '_run_apt_subprocess') + @unittest.skipIf( + sys.platform.startswith("win"), "System dependency test skipped on Windows" + ) + @patch.object(SystemInstaller, "_run_apt_subprocess") def test_simulate_installation_success(self, mock_run): """Test successful installation simulation.""" mock_run.return_value = 0 @@ -433,7 +446,7 @@ def test_simulate_installation_success(self, mock_run): dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } result = self.installer._simulate_installation(dependency, self.mock_context) @@ -443,20 +456,20 @@ def test_simulate_installation_success(self, mock_run): self.assertTrue(result.metadata["simulation"]) @regression_test - @patch.object(SystemInstaller, '_run_apt_subprocess') + @patch.object(SystemInstaller, "_run_apt_subprocess") def test_simulate_installation_failure(self, mock_run): """Test installation simulation failure.""" mock_run.return_value = 1 mock_run.side_effect = InstallationError( "Simulation failed", dependency_name="nonexistent", - error_code="APT_SIMULATION_FAILED" + error_code="APT_SIMULATION_FAILED", ) dependency = { "name": "nonexistent", "version_constraint": ">=1.0.0", - "package_manager": "apt" + "package_manager": "apt", } with self.assertRaises(InstallationError) as exc_info: @@ -466,24 +479,24 @@ def test_simulate_installation_failure(self, mock_run): self.assertEqual(exc_info.exception.error_code, "APT_SIMULATION_FAILED") @regression_test - @patch.object(SystemInstaller, '_run_apt_subprocess', return_value=0) + @patch.object(SystemInstaller, "_run_apt_subprocess", return_value=0) def test_uninstall_success(self, mock_execute): """Test successful uninstall.""" dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } - + result = self.installer.uninstall(dependency, self.mock_context) - + self.assertEqual(result.dependency_name, "curl") self.assertEqual(result.status, InstallationStatus.COMPLETED) self.assertEqual(result.metadata["operation"], "uninstall") @regression_test - @patch.object(SystemInstaller, '_run_apt_subprocess', return_value=0) + @patch.object(SystemInstaller, "_run_apt_subprocess", return_value=0) def test_uninstall_automated(self, mock_execute): """Test uninstall in automated mode.""" @@ -491,7 +504,7 @@ def test_uninstall_automated(self, mock_execute): dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } result = self.installer.uninstall(dependency, self.mock_context) @@ -501,20 +514,20 @@ def test_uninstall_automated(self, mock_execute): self.assertIn("-y", result.metadata.get("command_executed", [])) @regression_test - @patch.object(SystemInstaller, '_simulate_uninstall') + @patch.object(SystemInstaller, "_simulate_uninstall") def test_uninstall_simulation_mode(self, mock_simulate): """Test uninstall in simulation mode.""" mock_simulate.return_value = InstallationResult( dependency_name="curl", status=InstallationStatus.COMPLETED, - metadata={"operation": "uninstall", "simulation": True} + metadata={"operation": "uninstall", "simulation": True}, ) self.mock_context.simulation_mode = True dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } result = self.installer.uninstall(dependency, self.mock_context) @@ -527,7 +540,7 @@ def test_uninstall_simulation_mode(self, mock_simulate): class TestSystemInstallerIntegration(unittest.TestCase): """Integration tests for SystemInstaller using actual system dependencies.""" - + def setUp(self): """Set up integration test fixtures.""" self.installer = SystemInstaller() @@ -535,29 +548,27 @@ def setUp(self): environment_path=Path("/tmp/test_env"), environment_name="integration_test", simulation_mode=True, # Always use simulation for integration tests - extra_config={"automated": True} + extra_config={"automated": True}, ) - - @integration_test(scope="system") - @slow_test def test_validate_real_system_dependency(self): """Test validation with real system dependency from dummy package.""" # This mimics the dependency from system_dep_pkg dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } self.assertTrue(self.installer.validate_dependency(dependency)) @integration_test(scope="system") - @slow_test - @patch.object(SystemInstaller, '_is_platform_supported') - @patch.object(SystemInstaller, '_is_apt_available') - def test_can_install_real_dependency(self, mock_apt_available, mock_platform_supported): + @patch.object(SystemInstaller, "_is_platform_supported") + @patch.object(SystemInstaller, "_is_apt_available") + def test_can_install_real_dependency( + self, mock_apt_available, mock_platform_supported + ): """Test can_install with real system dependency.""" mock_platform_supported.return_value = True mock_apt_available.return_value = True @@ -566,147 +577,145 @@ def test_can_install_real_dependency(self, mock_apt_available, mock_platform_sup "type": "system", "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } self.assertTrue(self.installer.can_install(dependency)) @integration_test(scope="system") - @slow_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") + @unittest.skipIf( + sys.platform.startswith("win"), "System dependency test skipped on Windows" + ) def test_simulate_curl_installation(self): """Test simulating installation of curl package.""" dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } # Mock subprocess for simulation - with patch.object(self.installer, '_run_apt_subprocess') as mock_run: + with patch.object(self.installer, "_run_apt_subprocess") as mock_run: mock_run.return_value = 0 - result = self.installer._simulate_installation(dependency, self.test_context) + result = self.installer._simulate_installation( + dependency, self.test_context + ) self.assertEqual(result.dependency_name, "curl") self.assertEqual(result.status, InstallationStatus.COMPLETED) self.assertTrue(result.metadata["simulation"]) @integration_test(scope="system") - @slow_test def test_get_installation_info(self): """Test getting installation info for system dependency.""" dependency = { "type": "system", "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } - - with patch.object(self.installer, 'can_install', return_value=True): + + with patch.object(self.installer, "can_install", return_value=True): info = self.installer.get_installation_info(dependency, self.test_context) - + self.assertEqual(info["installer_type"], "system") self.assertEqual(info["dependency_name"], "curl") self.assertTrue(info["supported"]) @integration_test(scope="system") - @slow_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") - def test_install_real_dependency(self): - """Test installing a real system dependency.""" + @patch.object(SystemInstaller, "_run_apt_subprocess", return_value=0) + def test_install_real_dependency(self, mock_run): + """Test installing a system dependency (mocked subprocess).""" dependency = { - "name": "sl", # Use a rarer package than 'curl' + "name": "sl", "version_constraint": ">=5.02", - "package_manager": "apt" + "package_manager": "apt", } - # real installation result = self.installer.install(dependency, self.test_context) self.assertEqual(result.status, InstallationStatus.COMPLETED) self.assertTrue(result.metadata["automated"]) + mock_run.assert_called() @integration_test(scope="system") - @slow_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") - def test_install_integration_with_real_subprocess(self): - """Test install method with real _run_apt_subprocess execution. + @patch.object(SystemInstaller, "_run_apt_subprocess", return_value=0) + def test_install_integration_with_real_subprocess(self, mock_run): + """Test install method with mocked _run_apt_subprocess execution. - This integration test ensures that _run_apt_subprocess can actually run - without mocking, using apt-get --dry-run for safe testing. + This test ensures the install flow works correctly in simulation mode + with subprocess calls mocked. """ dependency = { "name": "curl", "version_constraint": ">=7.0.0", - "package_manager": "apt" + "package_manager": "apt", } - # Create a test context that uses simulation mode for safety + # Create a test context that uses simulation mode test_context = InstallationContext( environment_path=Path("/tmp/test_env"), environment_name="integration_test", simulation_mode=True, - extra_config={"automated": True} + extra_config={"automated": True}, ) - # This will call _run_apt_subprocess with real subprocess execution - # but in simulation mode, so it's safe result = self.installer.install(dependency, test_context) - + self.assertEqual(result.dependency_name, "curl") self.assertEqual(result.status, InstallationStatus.COMPLETED) self.assertTrue(result.metadata["simulation"]) self.assertEqual(result.metadata["package_manager"], "apt") self.assertTrue(result.metadata["automated"]) + mock_run.assert_called() @integration_test(scope="system") - @slow_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") - def test_run_apt_subprocess_direct_integration(self): - """Test _run_apt_subprocess directly with real system commands. + @patch("subprocess.Popen") + def test_run_apt_subprocess_direct_integration(self, mock_popen): + """Test _run_apt_subprocess directly with mocked subprocess. - This test verifies that _run_apt_subprocess can handle actual apt commands - without any mocking, using safe commands that don't modify the system. + This test verifies that _run_apt_subprocess correctly handles + subprocess calls and returns the expected return codes. """ + # Mock the Popen process + mock_process = MagicMock() + mock_process.communicate.return_value = ("", "") + mock_process.wait.return_value = 0 + mock_process.returncode = 0 + mock_popen.return_value = mock_process + # Test with apt-cache policy (read-only command) cmd = ["apt-cache", "policy", "curl"] returncode = self.installer._run_apt_subprocess(cmd) - - # Should return 0 (success) for a valid package query self.assertEqual(returncode, 0) # Test with apt-get dry-run (safe simulation command) cmd = ["apt-get", "install", "--dry-run", "-y", "curl"] returncode = self.installer._run_apt_subprocess(cmd) - - # Should return 0 (success) for a valid dry-run self.assertEqual(returncode, 0) - # Test with invalid package (should fail gracefully) + # Test with invalid package (apt-cache policy doesn't fail) cmd = ["apt-cache", "policy", "nonexistent-package-12345"] returncode = self.installer._run_apt_subprocess(cmd) - - # Should return 0 even for non-existent package (apt-cache policy doesn't fail) self.assertEqual(returncode, 0) @integration_test(scope="system") - @slow_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") - def test_install_with_version_constraint_integration(self): - """Test install method with version constraints and real subprocess calls.""" + @patch.object(SystemInstaller, "_run_apt_subprocess", return_value=0) + def test_install_with_version_constraint_integration(self, mock_run): + """Test install method with version constraints (mocked subprocess).""" # Test with exact version constraint dependency = { "name": "curl", "version_constraint": "==7.68.0", - "package_manager": "apt" + "package_manager": "apt", } test_context = InstallationContext( environment_path=Path("/tmp/test_env"), environment_name="integration_test", simulation_mode=True, - extra_config={"automated": True} + extra_config={"automated": True}, ) result = self.installer.install(dependency, test_context) @@ -716,18 +725,23 @@ def test_install_with_version_constraint_integration(self): self.assertTrue(result.metadata["simulation"]) # Check that the command includes the version constraint self.assertIn("curl", result.metadata["command_simulated"]) + mock_run.assert_called() @integration_test(scope="system") - @slow_test - @unittest.skipIf(sys.platform.startswith("win"), "System dependency test skipped on Windows") - def test_error_handling_in_run_apt_subprocess(self): - """Test error handling in _run_apt_subprocess with real commands.""" - # Test with completely invalid command + @patch("subprocess.Popen") + def test_error_handling_in_run_apt_subprocess(self, mock_popen): + """Test error handling in _run_apt_subprocess with invalid commands.""" + # Simulate FileNotFoundError for a nonexistent command + mock_popen.side_effect = FileNotFoundError( + "[Errno 2] No such file or directory: 'nonexistent-command-12345'" + ) + cmd = ["nonexistent-command-12345"] with self.assertRaises(InstallationError) as exc_info: self.installer._run_apt_subprocess(cmd) self.assertEqual(exc_info.exception.error_code, "APT_SUBPROCESS_ERROR") - self.assertIn("Unexpected error running apt command", exc_info.exception.message) - + self.assertIn( + "Unexpected error running apt command", exc_info.exception.message + ) diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/mcp/__init__.py b/tests/unit/mcp/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/mcp/test_adapter_protocol.py b/tests/unit/mcp/test_adapter_protocol.py new file mode 100644 index 0000000..e733a61 --- /dev/null +++ b/tests/unit/mcp/test_adapter_protocol.py @@ -0,0 +1,137 @@ +"""Unit tests for MCP Host Adapter protocol compliance. + +Test IDs: AP-01 to AP-06 (per 02-test_architecture_rebuild_v0.md) +Scope: Verify all adapters satisfy BaseAdapter protocol contract. +""" + +import unittest + +from hatch.mcp_host_config.models import MCPServerConfig, MCPHostType +from hatch.mcp_host_config.adapters import ( + get_adapter, + ClaudeAdapter, + CodexAdapter, + CursorAdapter, + GeminiAdapter, + KiroAdapter, + LMStudioAdapter, + VSCodeAdapter, +) + +# All adapter classes to test +ALL_ADAPTERS = [ + ClaudeAdapter, + CodexAdapter, + CursorAdapter, + GeminiAdapter, + KiroAdapter, + LMStudioAdapter, + VSCodeAdapter, +] + +# Map host types to their expected adapter classes +HOST_ADAPTER_MAP = { + MCPHostType.CLAUDE_DESKTOP: ClaudeAdapter, + MCPHostType.CLAUDE_CODE: ClaudeAdapter, + MCPHostType.CODEX: CodexAdapter, + MCPHostType.CURSOR: CursorAdapter, + MCPHostType.GEMINI: GeminiAdapter, + MCPHostType.KIRO: KiroAdapter, + MCPHostType.LMSTUDIO: LMStudioAdapter, + MCPHostType.VSCODE: VSCodeAdapter, +} + + +class TestAdapterProtocol(unittest.TestCase): + """Tests for adapter protocol compliance (AP-01 to AP-06).""" + + def test_AP01_all_adapters_have_get_supported_fields(self): + """AP-01: All adapters have `get_supported_fields()` returning frozenset.""" + for adapter_cls in ALL_ADAPTERS: + adapter = adapter_cls() + with self.subTest(adapter=adapter_cls.__name__): + self.assertTrue( + hasattr(adapter, "get_supported_fields"), + f"{adapter_cls.__name__} missing 'get_supported_fields'", + ) + self.assertTrue( + callable(adapter.get_supported_fields), + f"{adapter_cls.__name__}.get_supported_fields is not callable", + ) + supported = adapter.get_supported_fields() + self.assertIsInstance( + supported, + frozenset, + f"{adapter_cls.__name__}.get_supported_fields() did not return frozenset", + ) + + def test_AP02_all_adapters_have_validate(self): + """AP-02: All adapters have callable `validate()` method.""" + for adapter_cls in ALL_ADAPTERS: + adapter = adapter_cls() + with self.subTest(adapter=adapter_cls.__name__): + self.assertTrue( + hasattr(adapter, "validate"), + f"{adapter_cls.__name__} missing 'validate'", + ) + self.assertTrue( + callable(adapter.validate), + f"{adapter_cls.__name__}.validate is not callable", + ) + + def test_AP03_all_adapters_have_serialize(self): + """AP-03: All adapters have callable `serialize()` method.""" + for adapter_cls in ALL_ADAPTERS: + adapter = adapter_cls() + with self.subTest(adapter=adapter_cls.__name__): + self.assertTrue( + hasattr(adapter, "serialize"), + f"{adapter_cls.__name__} missing 'serialize'", + ) + self.assertTrue( + callable(adapter.serialize), + f"{adapter_cls.__name__}.serialize is not callable", + ) + + def test_AP04_serialize_never_returns_name(self): + """AP-04: `serialize()` never returns `name` field for any adapter.""" + config = MCPServerConfig(name="test-server", command="python") + + for adapter_cls in ALL_ADAPTERS: + adapter = adapter_cls() + with self.subTest(adapter=adapter_cls.__name__): + result = adapter.serialize(config) + self.assertNotIn( + "name", + result, + f"{adapter_cls.__name__}.serialize() returned 'name' field", + ) + + def test_AP05_serialize_never_returns_none_values(self): + """AP-05: `serialize()` returns no None values.""" + config = MCPServerConfig(name="test-server", command="python") + + for adapter_cls in ALL_ADAPTERS: + adapter = adapter_cls() + with self.subTest(adapter=adapter_cls.__name__): + result = adapter.serialize(config) + for key, value in result.items(): + self.assertIsNotNone( + value, + f"{adapter_cls.__name__}.serialize() returned None for '{key}'", + ) + + def test_AP06_get_adapter_returns_correct_type(self): + """AP-06: get_adapter() returns correct adapter for each host type.""" + for host_type, expected_cls in HOST_ADAPTER_MAP.items(): + with self.subTest(host=host_type.value): + adapter = get_adapter(host_type) + self.assertIsInstance( + adapter, + expected_cls, + f"get_adapter({host_type}) returned {type(adapter)}, expected {expected_cls}", + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/unit/mcp/test_adapter_registry.py b/tests/unit/mcp/test_adapter_registry.py new file mode 100644 index 0000000..9408835 --- /dev/null +++ b/tests/unit/mcp/test_adapter_registry.py @@ -0,0 +1,161 @@ +"""Unit tests for adapter registry. + +Test IDs: AR-01 to AR-08 (per 02-test_architecture_rebuild_v0.md) +Scope: Registry initialization, adapter lookup, registration. +""" + +import unittest + +from hatch.mcp_host_config.adapters import ( + AdapterRegistry, + get_adapter, + get_default_registry, + BaseAdapter, + ClaudeAdapter, + CodexAdapter, + CursorAdapter, + GeminiAdapter, + KiroAdapter, + LMStudioAdapter, + VSCodeAdapter, +) + + +class TestAdapterRegistry(unittest.TestCase): + """Tests for AdapterRegistry class (AR-01 to AR-08).""" + + def setUp(self): + """Create a fresh registry for each test.""" + self.registry = AdapterRegistry() + + def test_AR01_registry_has_all_default_hosts(self): + """AR-01: Registry initializes with all default host adapters.""" + expected_hosts = { + "claude-desktop", + "claude-code", + "codex", + "cursor", + "gemini", + "kiro", + "lmstudio", + "vscode", + } + + actual_hosts = set(self.registry.get_supported_hosts()) + + self.assertEqual(actual_hosts, expected_hosts) + + def test_AR02_get_adapter_returns_correct_type(self): + """AR-02: get_adapter() returns adapter with matching host_name.""" + test_cases = [ + ("claude-desktop", ClaudeAdapter), + ("claude-code", ClaudeAdapter), + ("codex", CodexAdapter), + ("cursor", CursorAdapter), + ("gemini", GeminiAdapter), + ("kiro", KiroAdapter), + ("lmstudio", LMStudioAdapter), + ("vscode", VSCodeAdapter), + ] + + for host_name, expected_cls in test_cases: + with self.subTest(host=host_name): + adapter = self.registry.get_adapter(host_name) + self.assertIsInstance(adapter, expected_cls) + self.assertEqual(adapter.host_name, host_name) + + def test_AR03_get_adapter_raises_for_unknown_host(self): + """AR-03: get_adapter() raises KeyError for unknown host.""" + with self.assertRaises(KeyError) as context: + self.registry.get_adapter("unknown-host") + + self.assertIn("unknown-host", str(context.exception)) + self.assertIn("Supported hosts", str(context.exception)) + + def test_AR04_has_adapter_returns_true_for_registered(self): + """AR-04: has_adapter() returns True for registered hosts.""" + for host_name in self.registry.get_supported_hosts(): + with self.subTest(host=host_name): + self.assertTrue(self.registry.has_adapter(host_name)) + + def test_AR05_has_adapter_returns_false_for_unknown(self): + """AR-05: has_adapter() returns False for unknown hosts.""" + self.assertFalse(self.registry.has_adapter("unknown-host")) + + def test_AR06_register_adds_new_adapter(self): + """AR-06: register() adds a new adapter to registry.""" + + # Create a custom adapter for testing + class CustomAdapter(BaseAdapter): + @property + def host_name(self): + return "custom-host" + + def get_supported_fields(self): + return frozenset({"command", "args"}) + + def validate(self, config): + pass + + def validate_filtered(self, filtered): + pass + + def serialize(self, config): + return {"command": config.command} + + custom = CustomAdapter() + self.registry.register(custom) + + self.assertTrue(self.registry.has_adapter("custom-host")) + self.assertIs(self.registry.get_adapter("custom-host"), custom) + + def test_AR07_register_raises_for_duplicate(self): + """AR-07: register() raises ValueError for duplicate host name.""" + # Try to register another Claude adapter + duplicate = ClaudeAdapter(variant="desktop") + + with self.assertRaises(ValueError) as context: + self.registry.register(duplicate) + + self.assertIn("claude-desktop", str(context.exception)) + self.assertIn("already registered", str(context.exception)) + + def test_AR08_unregister_removes_adapter(self): + """AR-08: unregister() removes adapter from registry.""" + self.assertTrue(self.registry.has_adapter("claude-desktop")) + + self.registry.unregister("claude-desktop") + + self.assertFalse(self.registry.has_adapter("claude-desktop")) + + def test_unregister_raises_for_unknown(self): + """unregister() raises KeyError for unknown host.""" + with self.assertRaises(KeyError): + self.registry.unregister("unknown-host") + + +class TestGlobalRegistryFunctions(unittest.TestCase): + """Tests for global registry convenience functions.""" + + def test_get_default_registry_returns_singleton(self): + """get_default_registry() returns same instance on multiple calls.""" + registry1 = get_default_registry() + registry2 = get_default_registry() + + self.assertIs(registry1, registry2) + + def test_get_adapter_uses_default_registry(self): + """get_adapter() function uses the default registry.""" + adapter = get_adapter("claude-desktop") + + self.assertIsInstance(adapter, ClaudeAdapter) + self.assertEqual(adapter.host_name, "claude-desktop") + + def test_get_adapter_raises_for_unknown(self): + """get_adapter() function raises KeyError for unknown host.""" + with self.assertRaises(KeyError): + get_adapter("unknown-host") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/unit/mcp/test_config_model.py b/tests/unit/mcp/test_config_model.py new file mode 100644 index 0000000..5e60df5 --- /dev/null +++ b/tests/unit/mcp/test_config_model.py @@ -0,0 +1,147 @@ +"""Unit tests for MCPServerConfig unified model. + +Test IDs: UM-01 to UM-07 (per 02-test_architecture_rebuild_v0.md) +Scope: Unified model validation, field defaults, transport configuration. +""" + +import unittest +from pydantic import ValidationError + +from hatch.mcp_host_config.models import MCPServerConfig + + +class TestMCPServerConfig(unittest.TestCase): + """Tests for MCPServerConfig unified model (UM-01 to UM-07).""" + + def test_UM01_valid_stdio_config(self): + """UM-01: Valid stdio config with command field.""" + config = MCPServerConfig(name="test", command="python") + + self.assertEqual(config.command, "python") + self.assertTrue(config.is_local_server) + self.assertFalse(config.is_remote_server) + + def test_UM02_valid_sse_config(self): + """UM-02: Valid SSE config with url field.""" + config = MCPServerConfig(name="test", url="https://example.com/mcp") + + self.assertEqual(config.url, "https://example.com/mcp") + self.assertFalse(config.is_local_server) + self.assertTrue(config.is_remote_server) + + def test_UM03_valid_http_config_gemini(self): + """UM-03: Valid HTTP config with httpUrl field (Gemini-style).""" + config = MCPServerConfig(name="test", httpUrl="https://example.com/http") + + self.assertEqual(config.httpUrl, "https://example.com/http") + # httpUrl is considered remote + self.assertTrue(config.is_remote_server) + + def test_UM04_allows_command_and_url(self): + """UM-04: Unified model allows both command and url (adapters validate).""" + # The unified model is permissive - adapters enforce host-specific rules + config = MCPServerConfig( + name="test", command="python", url="https://example.com" + ) + + self.assertEqual(config.command, "python") + self.assertEqual(config.url, "https://example.com") + + def test_UM05_reject_no_transport(self): + """UM-05: Reject config with no transport specified.""" + with self.assertRaises(ValidationError) as context: + MCPServerConfig(name="test") + + self.assertIn( + "At least one transport must be specified", str(context.exception) + ) + + def test_UM06_accept_all_fields(self): + """UM-06: Accept config with many fields set.""" + config = MCPServerConfig( + name="full-server", + command="python", + args=["-m", "server"], + env={"API_KEY": "secret"}, + type="stdio", + cwd="/workspace", + timeout=30000, + ) + + self.assertEqual(config.name, "full-server") + self.assertEqual(config.args, ["-m", "server"]) + self.assertEqual(config.env, {"API_KEY": "secret"}) + self.assertEqual(config.type, "stdio") + self.assertEqual(config.cwd, "/workspace") + self.assertEqual(config.timeout, 30000) + + def test_UM07_extra_fields_allowed(self): + """UM-07: Extra/unknown fields are allowed (extra='allow').""" + # Create config with extra fields via model_construct to bypass validation + config = MCPServerConfig.model_construct( + name="test", command="python", unknown_field="value" + ) + + # The model should allow extra fields + self.assertEqual(config.command, "python") + + def test_url_format_validation(self): + """Test URL format validation - must start with http:// or https://.""" + with self.assertRaises(ValidationError) as context: + MCPServerConfig(name="test", url="ftp://example.com") + + self.assertIn("URL must start with http:// or https://", str(context.exception)) + + def test_command_whitespace_stripped(self): + """Test command field strips leading/trailing whitespace.""" + config = MCPServerConfig(name="test", command=" python ") + + self.assertEqual(config.command, "python") + + def test_command_empty_rejected(self): + """Test empty command (after stripping) is rejected.""" + with self.assertRaises(ValidationError): + MCPServerConfig(name="test", command=" ") + + def test_serialization_roundtrip(self): + """Test JSON serialization roundtrip.""" + config = MCPServerConfig( + name="roundtrip-test", + command="python", + args=["server.py"], + env={"KEY": "value"}, + ) + + # Serialize to dict + data = config.model_dump(exclude_none=True) + + # Reconstruct from dict + reconstructed = MCPServerConfig.model_validate(data) + + self.assertEqual(reconstructed.name, config.name) + self.assertEqual(reconstructed.command, config.command) + self.assertEqual(reconstructed.args, config.args) + self.assertEqual(reconstructed.env, config.env) + + +class TestMCPServerConfigProperties(unittest.TestCase): + """Tests for MCPServerConfig computed properties.""" + + def test_is_local_server_with_command(self): + """Local server detection with command.""" + config = MCPServerConfig(name="test", command="python") + self.assertTrue(config.is_local_server) + + def test_is_remote_server_with_url(self): + """Remote server detection with url.""" + config = MCPServerConfig(name="test", url="https://example.com") + self.assertTrue(config.is_remote_server) + + def test_is_remote_server_with_httpUrl(self): + """Remote server detection with httpUrl.""" + config = MCPServerConfig(name="test", httpUrl="https://example.com/http") + self.assertTrue(config.is_remote_server) + + +if __name__ == "__main__": + unittest.main() diff --git a/wobble_results_20260210_140855.txt b/wobble_results_20260210_140855.txt new file mode 100644 index 0000000..b40edf8 --- /dev/null +++ b/wobble_results_20260210_140855.txt @@ -0,0 +1,710 @@ +=== Wobble Test Run === +Command: wobble --exclude-slow --log-file --log-verbosity 3 +Started: 2026-02-10T14:08:55.733130 + +PASS TestClaudeAdapterSerialization.test_AS01_claude_stdio_serialization (0.001s) +PASS TestClaudeAdapterSerialization.test_AS02_claude_sse_serialization (0.000s) +PASS TestCodexAdapterSerialization.test_AS06_codex_stdio_serialization (0.000s) +PASS TestGeminiAdapterSerialization.test_AS03_gemini_stdio_serialization (0.000s) +PASS TestGeminiAdapterSerialization.test_AS04_gemini_http_serialization (0.000s) +PASS TestKiroAdapterSerialization.test_AS07_kiro_stdio_serialization (0.000s) +PASS TestVSCodeAdapterSerialization.test_AS05_vscode_with_envfile (0.000s) +PASS TestColorEnum.test_amber_color_exists (0.000s) +PASS TestColorEnum.test_color_enum_exists (0.000s) +PASS TestColorEnum.test_color_enum_has_bright_colors (0.000s) +PASS TestColorEnum.test_color_enum_has_dim_colors (0.000s) +PASS TestColorEnum.test_color_enum_has_utility_colors (0.000s) +PASS TestColorEnum.test_color_enum_total_count (0.000s) +PASS TestColorEnum.test_color_values_are_ansi_codes (0.000s) +PASS TestColorEnum.test_reset_clears_formatting (0.000s) +PASS TestColorsEnabled.test_colors_disabled_when_no_color_set (0.000s) +PASS TestColorsEnabled.test_colors_disabled_when_no_color_truthy (0.000s) +PASS TestColorsEnabled.test_colors_disabled_when_not_tty (0.001s) +PASS TestColorsEnabled.test_colors_enabled_when_no_color_empty (0.000s) +PASS TestColorsEnabled.test_colors_enabled_when_no_color_unset (0.000s) +PASS TestColorsEnabled.test_colors_enabled_when_tty_and_no_no_color (0.001s) +PASS TestHighlightFunction.test_highlight_non_tty (0.001s) +PASS TestHighlightFunction.test_highlight_with_colors_disabled (0.000s) +PASS TestHighlightFunction.test_highlight_with_colors_enabled (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_colorterm_24bit (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_colorterm_truecolor (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_fallback_false (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_term_program_iterm (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_term_program_vscode (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_windows_terminal (0.000s) +PASS TestConsequenceTypeColorSemantics.test_constructive_types_use_green (0.000s) +PASS TestConsequenceTypeColorSemantics.test_destructive_types_use_red (0.000s) +PASS TestConsequenceTypeColorSemantics.test_informational_type_uses_cyan (0.000s) +PASS TestConsequenceTypeColorSemantics.test_modification_types_use_yellow (0.000s) +PASS TestConsequenceTypeColorSemantics.test_noop_types_use_gray (0.000s) +PASS TestConsequenceTypeColorSemantics.test_recovery_type_uses_blue (0.000s) +PASS TestConsequenceTypeColorSemantics.test_transfer_type_uses_magenta (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_enum_exists (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_all_constructive_types (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_all_destructive_types (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_all_modification_types (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_all_noop_types (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_informational_type (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_recovery_type (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_transfer_type (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_total_count (0.000s) +PASS TestConsequenceTypeProperties.test_all_types_have_prompt_color (0.000s) +PASS TestConsequenceTypeProperties.test_all_types_have_prompt_label (0.000s) +PASS TestConsequenceTypeProperties.test_all_types_have_result_color (0.000s) +PASS TestConsequenceTypeProperties.test_all_types_have_result_label (0.000s) +PASS TestConsequenceTypeProperties.test_irregular_verbs_prompt_equals_result (0.000s) +PASS TestConsequenceTypeProperties.test_regular_verbs_result_ends_with_ed (0.000s) +PASS TestFormatInfo.test_format_info_basic (0.000s) +PASS TestFormatInfo.test_format_info_no_color_in_non_tty (0.000s) +PASS TestFormatInfo.test_format_info_output_format (0.000s) +PASS TestFormatValidationError.test_format_validation_error_basic (0.000s) +PASS TestFormatValidationError.test_format_validation_error_full (0.000s) +PASS TestFormatValidationError.test_format_validation_error_no_color_in_non_tty (0.000s) +PASS TestFormatValidationError.test_format_validation_error_with_field (0.000s) +PASS TestFormatValidationError.test_format_validation_error_with_suggestion (0.000s) +PASS TestHatchArgumentParser.test_argparse_error_exit_code_2 (0.164s) +PASS TestHatchArgumentParser.test_argparse_error_has_error_prefix (0.168s) +PASS TestHatchArgumentParser.test_argparse_error_no_ansi_in_pipe (0.162s) +PASS TestHatchArgumentParser.test_argparse_error_unrecognized_argument (0.157s) +PASS TestHatchArgumentParser.test_hatch_argument_parser_class_exists (0.000s) +PASS TestHatchArgumentParser.test_hatch_argument_parser_has_error_method (0.000s) +PASS TestValidationError.test_validation_error_attributes (0.000s) +PASS TestValidationError.test_validation_error_can_be_raised (0.000s) +PASS TestValidationError.test_validation_error_is_exception (0.000s) +PASS TestValidationError.test_validation_error_optional_field (0.000s) +PASS TestValidationError.test_validation_error_optional_suggestion (0.000s) +PASS TestValidationError.test_validation_error_str_returns_message (0.000s) +PASS TestConsequence.test_consequence_accepts_children_list (0.000s) +PASS TestConsequence.test_consequence_accepts_type_and_message (0.000s) +PASS TestConsequence.test_consequence_children_are_consequence_instances (0.000s) +PASS TestConsequence.test_consequence_children_default_not_shared (0.000s) +PASS TestConsequence.test_consequence_dataclass_exists (0.000s) +PASS TestConsequence.test_consequence_default_children_is_empty_list (0.000s) +PASS TestConversionReportIntegration.test_add_from_conversion_report_method_exists (0.000s) +PASS TestConversionReportIntegration.test_all_fields_mapped_no_data_loss (0.003s) +PASS TestConversionReportIntegration.test_empty_conversion_report_handled (0.000s) +PASS TestConversionReportIntegration.test_field_name_preserved_in_mapping (0.000s) +PASS TestConversionReportIntegration.test_old_new_values_preserved (0.000s) +PASS TestConversionReportIntegration.test_resource_consequence_type_from_operation (0.000s) +PASS TestConversionReportIntegration.test_server_name_in_resource_message (0.000s) +PASS TestConversionReportIntegration.test_target_host_in_resource_message (0.000s) +PASS TestConversionReportIntegration.test_unchanged_maps_to_unchanged_type (0.000s) +PASS TestConversionReportIntegration.test_unsupported_maps_to_skip_type (0.000s) +PASS TestConversionReportIntegration.test_updated_maps_to_update_type (0.000s) +PASS TestReportError.test_report_error_basic (0.000s) +PASS TestReportError.test_report_error_empty_summary_no_output (0.000s) +PASS TestReportError.test_report_error_no_color_in_non_tty (0.000s) +PASS TestReportError.test_report_error_none_details_handled (0.000s) +PASS TestReportError.test_report_error_with_details (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_ascii_fallback (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_basic (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_empty_lists (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_failure_reason_shown (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_no_color_in_non_tty (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_summary_line (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_unicode_symbols (0.000s) +PASS TestResultReporter.test_result_reporter_accepts_command_name (0.000s) +PASS TestResultReporter.test_result_reporter_add_consequence (0.000s) +PASS TestResultReporter.test_result_reporter_add_with_children (0.000s) +PASS TestResultReporter.test_result_reporter_command_name_stored (0.000s) +PASS TestResultReporter.test_result_reporter_consequence_data_preserved (0.000s) +PASS TestResultReporter.test_result_reporter_consequences_tracked_in_order (0.000s) +PASS TestResultReporter.test_result_reporter_dry_run_default_false (0.000s) +PASS TestResultReporter.test_result_reporter_dry_run_stored (0.000s) +PASS TestResultReporter.test_result_reporter_empty_consequences (0.000s) +PASS TestResultReporter.test_result_reporter_exists (0.000s) +PASS TestFieldFiltering.test_RF01_name_never_in_gemini_output (0.000s) +PASS TestFieldFiltering.test_RF02_name_never_in_claude_output (0.000s) +PASS TestFieldFiltering.test_RF03_type_not_in_gemini_output (0.000s) +PASS TestFieldFiltering.test_RF04_type_not_in_kiro_output (0.000s) +PASS TestFieldFiltering.test_RF05_type_not_in_codex_output (0.000s) +PASS TestFieldFiltering.test_RF06_type_IS_in_claude_output (0.000s) +PASS TestFieldFiltering.test_RF07_type_IS_in_vscode_output (0.000s) +PASS TestFieldFiltering.test_cursor_type_behavior (0.000s) +PASS TestFieldFiltering.test_name_never_in_any_adapter_output (0.000s) +ERROR _FailedTest.test_cli_version (0.000s) + Error: ImportError: Failed to import test module: test_cli_version +Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/loader.py", line 396, in _find_test_path + module = self._get_module_from_name(name) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/loader.py", line 339, in _get_module_from_name + __import__(name) + File "/Users/hacker/Documents/src/CrackingShells/Hatch/tests/test_cli_version.py", line 23, in + from hatch.cli_hatch import main + File "/Users/hacker/Documents/src/CrackingShells/Hatch/hatch/cli_hatch.py", line 64, in + from hatch.cli.cli_mcp import ( +ImportError: cannot import name 'handle_mcp_show' from 'hatch.cli.cli_mcp' (/Users/hacker/Documents/src/CrackingShells/Hatch/hatch/cli/cli_mcp.py) + + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 634, in run + self._callTestMethod(testMethod) + ... (traceback truncated) +PASS TestEnvironmentVariableScenarios.test_all_environment_variable_scenarios (0.004s) +PASS TestInstallationPlanVariations.test_non_tty_with_complex_plan (0.001s) +PASS TestInstallationPlanVariations.test_non_tty_with_empty_plan (0.001s) +PASS TestUserConsentHandling.test_environment_variable_case_insensitive (0.001s) +PASS TestUserConsentHandling.test_environment_variable_invalid_value (0.001s) +PASS TestUserConsentHandling.test_environment_variable_numeric_true (0.001s) +PASS TestUserConsentHandling.test_environment_variable_string_true (0.001s) +PASS TestUserConsentHandling.test_eof_error_handling (0.001s) +PASS TestUserConsentHandling.test_keyboard_interrupt_handling (0.001s) +PASS TestUserConsentHandling.test_non_tty_environment_auto_approve (0.001s) +PASS TestUserConsentHandling.test_tty_environment_invalid_then_valid_input (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_approves (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_approves_full_word (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_default_deny (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_denies (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_denies_full_word (0.001s) +SKIP TestDockerInstaller.test_can_install_docker_unavailable (0.000s) +PASS TestDockerInstaller.test_can_install_valid_dependency (0.001s) +PASS TestDockerInstaller.test_can_install_wrong_type (0.000s) +PASS TestDockerInstaller.test_get_installation_info_docker_unavailable (0.000s) +SKIP TestDockerInstaller.test_get_installation_info_image_installed (0.000s) +SKIP TestDockerInstaller.test_install_failure (0.000s) +PASS TestDockerInstaller.test_install_invalid_dependency (0.000s) +PASS TestDockerInstaller.test_install_simulation_mode (0.000s) +SKIP TestDockerInstaller.test_install_success (0.000s) +PASS TestDockerInstaller.test_installer_type (0.000s) +PASS TestDockerInstaller.test_resolve_docker_tag (0.000s) +PASS TestDockerInstaller.test_supported_schemes (0.000s) +PASS TestDockerInstaller.test_uninstall_simulation_mode (0.000s) +SKIP TestDockerInstaller.test_uninstall_success (0.000s) +PASS TestDockerInstaller.test_validate_dependency_invalid_registry (0.000s) +PASS TestDockerInstaller.test_validate_dependency_invalid_type (0.000s) +PASS TestDockerInstaller.test_validate_dependency_invalid_version_constraint (0.000s) +PASS TestDockerInstaller.test_validate_dependency_missing_name (0.000s) +PASS TestDockerInstaller.test_validate_dependency_missing_version_constraint (0.000s) +PASS TestDockerInstaller.test_validate_dependency_valid (0.000s) +PASS TestDockerInstaller.test_version_constraint_validation (0.000s) +FAIL PackageEnvironmentTests.test_add_package_environment_variable_compatibility (0.000s) + Error: AssertionError: False is not true : Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 630, in run + self._callSetUp() + ... (traceback truncated) +FAIL PackageEnvironmentTests.test_add_package_non_tty_auto_approve (0.000s) + Error: AssertionError: False is not true : Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 630, in run + self._callSetUp() + ... (traceback truncated) +FAIL PackageEnvironmentTests.test_add_package_with_dependencies_non_tty (0.000s) + Error: AssertionError: False is not true : Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 630, in run + self._callSetUp() + ... (traceback truncated) +FAIL PackageEnvironmentTests.test_environment_variable_case_variations (0.000s) + Error: AssertionError: False is not true : Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 630, in run + self._callSetUp() + ... (traceback truncated) +ERROR _ErrorHolder.setUpClass failed in TestHatchInstaller (test_hatch_installer.py) (0.000s) + Error: AssertionError: Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/suite.py", line 166, in _handleClassSetUp + setUpClass() + File "/Users/hacker/Documents/src/CrackingShells/Hatch/tests/test_hatch_installer.py", line 24, in setUpClass + cls.hatch_dev_path.exists() + ... (traceback truncated) +PASS BaseInstallerTests.test_installation_context_creation (0.000s) +PASS BaseInstallerTests.test_installation_context_with_config (0.000s) +PASS BaseInstallerTests.test_installation_error (0.000s) +PASS BaseInstallerTests.test_installation_result_creation (0.000s) +PASS BaseInstallerTests.test_installation_status_enum (0.000s) +PASS BaseInstallerTests.test_mock_installer_get_installation_info (0.000s) +PASS BaseInstallerTests.test_mock_installer_install (0.000s) +PASS BaseInstallerTests.test_mock_installer_interface (0.000s) +PASS BaseInstallerTests.test_mock_installer_uninstall_not_implemented (0.000s) +PASS BaseInstallerTests.test_mock_installer_validation (0.000s) +PASS BaseInstallerTests.test_progress_callback_support (0.000s) +PASS TestPythonEnvironmentManager.test_conda_env_exists (0.414s) +PASS TestPythonEnvironmentManager.test_conda_env_not_exists (0.231s) +PASS TestPythonEnvironmentManager.test_create_python_environment_already_exists (0.237s) +PASS TestPythonEnvironmentManager.test_create_python_environment_no_conda (0.227s) +PASS TestPythonEnvironmentManager.test_create_python_environment_success (0.226s) +PASS TestPythonEnvironmentManager.test_detect_conda_mamba_conda_only (0.231s) +PASS TestPythonEnvironmentManager.test_detect_conda_mamba_none_available (0.234s) +PASS TestPythonEnvironmentManager.test_detect_conda_mamba_with_mamba (0.238s) +PASS TestPythonEnvironmentManager.test_get_conda_env_name (0.235s) +PASS TestPythonEnvironmentManager.test_get_environment_activation_info_env_not_exists (0.460s) +PASS TestPythonEnvironmentManager.test_get_environment_activation_info_no_python (0.456s) +PASS TestPythonEnvironmentManager.test_get_environment_activation_info_unix (0.460s) +FAIL TestPythonEnvironmentManager.test_get_environment_activation_info_windows (0.452s) + Error: AssertionError: 'C:\\fake\\env' not found in ['C:/fake/env:C:/fake/env/Scripts:C:/fake/env/Library/bin:/Users/hacker/miniforge3/envs/forHatch-dev/bin:/Users/hacker/.nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/opt/pmk/env/global/bin:/Library/Apple/usr/bin:/Library/TeX/texbin:/Users/hacker/.nvm/versions/node/v24.13.0/bin:/Users/hacker/miniforge3/condabin:/Users/hacker/.local/bin:/Users/hacker/.cargo/bin:/Users/hacker/Documents/bin/OpenUSD/bin:/Users/hacker/.lmstudio/bin:/Users/hacker/Documents/bin/OpenUSD/bin:/Users/hacker/.lmstudio/bin'] + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 634, in run + self._callTestMethod(testMethod) + ... (traceback truncated) +PASS TestPythonEnvironmentManager.test_get_preferred_executable (0.226s) +PASS TestPythonEnvironmentManager.test_get_python_executable_exists (0.229s) +PASS TestPythonEnvironmentManager.test_get_python_executable_not_exists (0.229s) +PASS TestPythonEnvironmentManager.test_get_python_executable_path_unix (0.231s) +PASS TestPythonEnvironmentManager.test_get_python_executable_path_windows (0.233s) +PASS TestPythonEnvironmentManager.test_init (0.227s) +PASS TestPythonEnvironmentManager.test_is_available_no_conda (0.456s) +PASS TestPythonEnvironmentManager.test_is_available_with_conda (0.236s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_environment_diagnostics_structure (0.261s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_get_manager_info_structure (0.224s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_interactive_unix (0.255s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_interactive_windows (0.234s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_no_python_executable (0.222s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_nonexistent_environment (0.263s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_with_command (0.227s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_manager_diagnostics_structure (0.452s) +PASS TestPythonInstaller.test_can_install_python_type (0.001s) +PASS TestPythonInstaller.test_can_install_wrong_type (0.000s) +PASS TestPythonInstaller.test_install_failure (0.001s) +PASS TestPythonInstaller.test_install_simulation_mode (0.001s) +PASS TestPythonInstaller.test_install_success (0.000s) +PASS TestPythonInstaller.test_run_pip_subprocess_exception (0.001s) +PASS TestPythonInstaller.test_uninstall_failure (0.000s) +PASS TestPythonInstaller.test_uninstall_success (0.000s) +PASS TestPythonInstaller.test_validate_dependency_invalid_missing_fields (0.000s) +PASS TestPythonInstaller.test_validate_dependency_invalid_package_manager (0.000s) +PASS TestPythonInstaller.test_validate_dependency_valid (0.000s) +PASS TestInstallerRegistry.test_error_on_unknown_type (0.000s) +PASS TestInstallerRegistry.test_get_installer_instance (0.000s) +PASS TestInstallerRegistry.test_registered_types (0.000s) +PASS TestInstallerRegistry.test_registry_repr_and_len (0.000s) +PASS RegistryRetrieverTests.test_online_mode (1.439s) +PASS RegistryRetrieverTests.test_persistent_timestamp_across_cli_invocations (0.156s) +PASS RegistryRetrieverTests.test_persistent_timestamp_edge_cases (0.002s) +PASS RegistryRetrieverTests.test_registry_cache_management (0.468s) +PASS RegistryRetrieverTests.test_registry_init (0.002s) +PASS TestSystemInstaller.test_build_apt_command_automated (0.000s) +PASS TestSystemInstaller.test_build_apt_command_basic (0.000s) +PASS TestSystemInstaller.test_build_apt_command_exact_version (0.000s) +PASS TestSystemInstaller.test_can_install_apt_not_available (0.000s) +PASS TestSystemInstaller.test_can_install_unsupported_platform (0.000s) +PASS TestSystemInstaller.test_can_install_valid_dependency (0.000s) +PASS TestSystemInstaller.test_can_install_wrong_type (0.000s) +PASS TestSystemInstaller.test_install_apt_failure (0.000s) +PASS TestSystemInstaller.test_install_invalid_dependency (0.000s) +PASS TestSystemInstaller.test_install_simulation_mode (0.000s) +PASS TestSystemInstaller.test_install_success (0.033s) +PASS TestSystemInstaller.test_installer_type (0.000s) +PASS TestSystemInstaller.test_is_apt_available_false (0.001s) +PASS TestSystemInstaller.test_is_apt_available_true (0.000s) +PASS TestSystemInstaller.test_is_platform_supported_debian (0.000s) +PASS TestSystemInstaller.test_is_platform_supported_ubuntu (0.001s) +PASS TestSystemInstaller.test_is_platform_supported_unsupported (0.000s) +PASS TestSystemInstaller.test_parse_apt_error_generic (0.000s) +PASS TestSystemInstaller.test_parse_apt_error_package_not_found (0.000s) +PASS TestSystemInstaller.test_parse_apt_error_permission_denied (0.000s) +PASS TestSystemInstaller.test_simulate_installation_failure (0.000s) +PASS TestSystemInstaller.test_simulate_installation_success (0.000s) +PASS TestSystemInstaller.test_supported_schemes (0.000s) +PASS TestSystemInstaller.test_uninstall_automated (0.000s) +PASS TestSystemInstaller.test_uninstall_simulation_mode (0.000s) +PASS TestSystemInstaller.test_uninstall_success (0.000s) +PASS TestSystemInstaller.test_validate_dependency_invalid_package_manager (0.000s) +PASS TestSystemInstaller.test_validate_dependency_invalid_version_constraint (0.000s) +PASS TestSystemInstaller.test_validate_dependency_missing_name (0.000s) +PASS TestSystemInstaller.test_validate_dependency_missing_version_constraint (0.000s) +PASS TestSystemInstaller.test_validate_dependency_valid (0.000s) +PASS TestSystemInstaller.test_verify_installation_failure (0.000s) +PASS TestSystemInstaller.test_verify_installation_success (0.000s) +PASS TestAdapterProtocol.test_AP01_all_adapters_have_get_supported_fields (0.000s) +PASS TestAdapterProtocol.test_AP02_all_adapters_have_validate (0.000s) +PASS TestAdapterProtocol.test_AP03_all_adapters_have_serialize (0.000s) +PASS TestAdapterProtocol.test_AP04_serialize_never_returns_name (0.000s) +PASS TestAdapterProtocol.test_AP05_serialize_never_returns_none_values (0.000s) +PASS TestAdapterProtocol.test_AP06_get_adapter_returns_correct_type (0.000s) +PASS TestAdapterRegistry.test_AR01_registry_has_all_default_hosts (0.000s) +PASS TestAdapterRegistry.test_AR02_get_adapter_returns_correct_type (0.000s) +PASS TestAdapterRegistry.test_AR03_get_adapter_raises_for_unknown_host (0.000s) +PASS TestAdapterRegistry.test_AR04_has_adapter_returns_true_for_registered (0.000s) +PASS TestAdapterRegistry.test_AR05_has_adapter_returns_false_for_unknown (0.000s) +PASS TestAdapterRegistry.test_AR06_register_adds_new_adapter (0.000s) +PASS TestAdapterRegistry.test_AR07_register_raises_for_duplicate (0.000s) +PASS TestAdapterRegistry.test_AR08_unregister_removes_adapter (0.000s) +PASS TestAdapterRegistry.test_unregister_raises_for_unknown (0.000s) +PASS TestGlobalRegistryFunctions.test_get_adapter_raises_for_unknown (0.000s) +PASS TestGlobalRegistryFunctions.test_get_adapter_uses_default_registry (0.000s) +PASS TestGlobalRegistryFunctions.test_get_default_registry_returns_singleton (0.000s) +PASS TestMCPServerConfig.test_UM01_valid_stdio_config (0.000s) +PASS TestMCPServerConfig.test_UM02_valid_sse_config (0.000s) +PASS TestMCPServerConfig.test_UM03_valid_http_config_gemini (0.000s) +PASS TestMCPServerConfig.test_UM04_allows_command_and_url (0.000s) +PASS TestMCPServerConfig.test_UM05_reject_no_transport (0.000s) +PASS TestMCPServerConfig.test_UM06_accept_all_fields (0.000s) +PASS TestMCPServerConfig.test_UM07_extra_fields_allowed (0.000s) +PASS TestMCPServerConfig.test_command_empty_rejected (0.000s) +PASS TestMCPServerConfig.test_command_whitespace_stripped (0.000s) +PASS TestMCPServerConfig.test_serialization_roundtrip (0.000s) +PASS TestMCPServerConfig.test_url_format_validation (0.000s) +PASS TestMCPServerConfigProperties.test_is_local_server_with_command (0.000s) +PASS TestMCPServerConfigProperties.test_is_remote_server_with_httpUrl (0.000s) +PASS TestMCPServerConfigProperties.test_is_remote_server_with_url (0.000s) +PASS TestClaudeAdapterSerialization.test_AS01_claude_stdio_serialization (0.000s) +PASS TestClaudeAdapterSerialization.test_AS02_claude_sse_serialization (0.000s) +PASS TestCodexAdapterSerialization.test_AS06_codex_stdio_serialization (0.000s) +PASS TestGeminiAdapterSerialization.test_AS03_gemini_stdio_serialization (0.000s) +PASS TestGeminiAdapterSerialization.test_AS04_gemini_http_serialization (0.000s) +PASS TestKiroAdapterSerialization.test_AS07_kiro_stdio_serialization (0.000s) +PASS TestVSCodeAdapterSerialization.test_AS05_vscode_with_envfile (0.000s) +PASS TestColorEnum.test_amber_color_exists (0.000s) +PASS TestColorEnum.test_color_enum_exists (0.000s) +PASS TestColorEnum.test_color_enum_has_bright_colors (0.000s) +PASS TestColorEnum.test_color_enum_has_dim_colors (0.000s) +PASS TestColorEnum.test_color_enum_has_utility_colors (0.000s) +PASS TestColorEnum.test_color_enum_total_count (0.000s) +PASS TestColorEnum.test_color_values_are_ansi_codes (0.000s) +PASS TestColorEnum.test_reset_clears_formatting (0.000s) +PASS TestColorsEnabled.test_colors_disabled_when_no_color_set (0.000s) +PASS TestColorsEnabled.test_colors_disabled_when_no_color_truthy (0.000s) +PASS TestColorsEnabled.test_colors_disabled_when_not_tty (0.001s) +PASS TestColorsEnabled.test_colors_enabled_when_no_color_empty (0.000s) +PASS TestColorsEnabled.test_colors_enabled_when_no_color_unset (0.000s) +PASS TestColorsEnabled.test_colors_enabled_when_tty_and_no_no_color (0.001s) +PASS TestHighlightFunction.test_highlight_non_tty (0.001s) +PASS TestHighlightFunction.test_highlight_with_colors_disabled (0.000s) +PASS TestHighlightFunction.test_highlight_with_colors_enabled (0.001s) +PASS TestTrueColorDetection.test_truecolor_detection_colorterm_24bit (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_colorterm_truecolor (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_fallback_false (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_term_program_iterm (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_term_program_vscode (0.000s) +PASS TestTrueColorDetection.test_truecolor_detection_windows_terminal (0.000s) +PASS TestConsequenceTypeColorSemantics.test_constructive_types_use_green (0.000s) +PASS TestConsequenceTypeColorSemantics.test_destructive_types_use_red (0.000s) +PASS TestConsequenceTypeColorSemantics.test_informational_type_uses_cyan (0.000s) +PASS TestConsequenceTypeColorSemantics.test_modification_types_use_yellow (0.000s) +PASS TestConsequenceTypeColorSemantics.test_noop_types_use_gray (0.000s) +PASS TestConsequenceTypeColorSemantics.test_recovery_type_uses_blue (0.000s) +PASS TestConsequenceTypeColorSemantics.test_transfer_type_uses_magenta (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_enum_exists (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_all_constructive_types (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_all_destructive_types (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_all_modification_types (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_all_noop_types (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_informational_type (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_recovery_type (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_has_transfer_type (0.000s) +PASS TestConsequenceTypeEnum.test_consequence_type_total_count (0.000s) +PASS TestConsequenceTypeProperties.test_all_types_have_prompt_color (0.000s) +PASS TestConsequenceTypeProperties.test_all_types_have_prompt_label (0.000s) +PASS TestConsequenceTypeProperties.test_all_types_have_result_color (0.000s) +PASS TestConsequenceTypeProperties.test_all_types_have_result_label (0.000s) +PASS TestConsequenceTypeProperties.test_irregular_verbs_prompt_equals_result (0.000s) +PASS TestConsequenceTypeProperties.test_regular_verbs_result_ends_with_ed (0.000s) +PASS TestFormatInfo.test_format_info_basic (0.000s) +PASS TestFormatInfo.test_format_info_no_color_in_non_tty (0.000s) +PASS TestFormatInfo.test_format_info_output_format (0.000s) +PASS TestFormatValidationError.test_format_validation_error_basic (0.000s) +PASS TestFormatValidationError.test_format_validation_error_full (0.000s) +PASS TestFormatValidationError.test_format_validation_error_no_color_in_non_tty (0.000s) +PASS TestFormatValidationError.test_format_validation_error_with_field (0.000s) +PASS TestFormatValidationError.test_format_validation_error_with_suggestion (0.000s) +PASS TestHatchArgumentParser.test_argparse_error_exit_code_2 (0.177s) +PASS TestHatchArgumentParser.test_argparse_error_has_error_prefix (0.165s) +PASS TestHatchArgumentParser.test_argparse_error_no_ansi_in_pipe (0.164s) +PASS TestHatchArgumentParser.test_argparse_error_unrecognized_argument (0.160s) +PASS TestHatchArgumentParser.test_hatch_argument_parser_class_exists (0.000s) +PASS TestHatchArgumentParser.test_hatch_argument_parser_has_error_method (0.000s) +PASS TestValidationError.test_validation_error_attributes (0.000s) +PASS TestValidationError.test_validation_error_can_be_raised (0.000s) +PASS TestValidationError.test_validation_error_is_exception (0.000s) +PASS TestValidationError.test_validation_error_optional_field (0.000s) +PASS TestValidationError.test_validation_error_optional_suggestion (0.000s) +PASS TestValidationError.test_validation_error_str_returns_message (0.000s) +PASS TestConsequence.test_consequence_accepts_children_list (0.000s) +PASS TestConsequence.test_consequence_accepts_type_and_message (0.000s) +PASS TestConsequence.test_consequence_children_are_consequence_instances (0.000s) +PASS TestConsequence.test_consequence_children_default_not_shared (0.000s) +PASS TestConsequence.test_consequence_dataclass_exists (0.000s) +PASS TestConsequence.test_consequence_default_children_is_empty_list (0.000s) +PASS TestConversionReportIntegration.test_add_from_conversion_report_method_exists (0.000s) +PASS TestConversionReportIntegration.test_all_fields_mapped_no_data_loss (0.000s) +PASS TestConversionReportIntegration.test_empty_conversion_report_handled (0.000s) +PASS TestConversionReportIntegration.test_field_name_preserved_in_mapping (0.000s) +PASS TestConversionReportIntegration.test_old_new_values_preserved (0.000s) +PASS TestConversionReportIntegration.test_resource_consequence_type_from_operation (0.000s) +PASS TestConversionReportIntegration.test_server_name_in_resource_message (0.000s) +PASS TestConversionReportIntegration.test_target_host_in_resource_message (0.000s) +PASS TestConversionReportIntegration.test_unchanged_maps_to_unchanged_type (0.000s) +PASS TestConversionReportIntegration.test_unsupported_maps_to_skip_type (0.000s) +PASS TestConversionReportIntegration.test_updated_maps_to_update_type (0.000s) +PASS TestReportError.test_report_error_basic (0.000s) +PASS TestReportError.test_report_error_empty_summary_no_output (0.000s) +PASS TestReportError.test_report_error_no_color_in_non_tty (0.000s) +PASS TestReportError.test_report_error_none_details_handled (0.000s) +PASS TestReportError.test_report_error_with_details (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_ascii_fallback (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_basic (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_empty_lists (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_failure_reason_shown (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_no_color_in_non_tty (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_summary_line (0.000s) +PASS TestReportPartialSuccess.test_report_partial_success_unicode_symbols (0.000s) +PASS TestResultReporter.test_result_reporter_accepts_command_name (0.000s) +PASS TestResultReporter.test_result_reporter_add_consequence (0.000s) +PASS TestResultReporter.test_result_reporter_add_with_children (0.000s) +PASS TestResultReporter.test_result_reporter_command_name_stored (0.000s) +PASS TestResultReporter.test_result_reporter_consequence_data_preserved (0.000s) +PASS TestResultReporter.test_result_reporter_consequences_tracked_in_order (0.000s) +PASS TestResultReporter.test_result_reporter_dry_run_default_false (0.000s) +PASS TestResultReporter.test_result_reporter_dry_run_stored (0.000s) +PASS TestResultReporter.test_result_reporter_empty_consequences (0.000s) +PASS TestResultReporter.test_result_reporter_exists (0.000s) +PASS TestFieldFiltering.test_RF01_name_never_in_gemini_output (0.000s) +PASS TestFieldFiltering.test_RF02_name_never_in_claude_output (0.000s) +PASS TestFieldFiltering.test_RF03_type_not_in_gemini_output (0.000s) +PASS TestFieldFiltering.test_RF04_type_not_in_kiro_output (0.000s) +PASS TestFieldFiltering.test_RF05_type_not_in_codex_output (0.000s) +PASS TestFieldFiltering.test_RF06_type_IS_in_claude_output (0.000s) +PASS TestFieldFiltering.test_RF07_type_IS_in_vscode_output (0.000s) +PASS TestFieldFiltering.test_cursor_type_behavior (0.000s) +PASS TestFieldFiltering.test_name_never_in_any_adapter_output (0.000s) +ERROR _FailedTest.test_cli_version (0.000s) + Error: ImportError: Failed to import test module: test_cli_version +Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/loader.py", line 396, in _find_test_path + module = self._get_module_from_name(name) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/loader.py", line 339, in _get_module_from_name + __import__(name) + File "/Users/hacker/Documents/src/CrackingShells/Hatch/Tests/test_cli_version.py", line 23, in + from hatch.cli_hatch import main + File "/Users/hacker/Documents/src/CrackingShells/Hatch/hatch/cli_hatch.py", line 64, in + from hatch.cli.cli_mcp import ( +ImportError: cannot import name 'handle_mcp_show' from 'hatch.cli.cli_mcp' (/Users/hacker/Documents/src/CrackingShells/Hatch/hatch/cli/cli_mcp.py) + + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 634, in run + self._callTestMethod(testMethod) + ... (traceback truncated) +PASS TestEnvironmentVariableScenarios.test_all_environment_variable_scenarios (0.003s) +PASS TestInstallationPlanVariations.test_non_tty_with_complex_plan (0.001s) +PASS TestInstallationPlanVariations.test_non_tty_with_empty_plan (0.001s) +PASS TestUserConsentHandling.test_environment_variable_case_insensitive (0.001s) +PASS TestUserConsentHandling.test_environment_variable_invalid_value (0.001s) +PASS TestUserConsentHandling.test_environment_variable_numeric_true (0.001s) +PASS TestUserConsentHandling.test_environment_variable_string_true (0.001s) +PASS TestUserConsentHandling.test_eof_error_handling (0.001s) +PASS TestUserConsentHandling.test_keyboard_interrupt_handling (0.001s) +PASS TestUserConsentHandling.test_non_tty_environment_auto_approve (0.001s) +PASS TestUserConsentHandling.test_tty_environment_invalid_then_valid_input (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_approves (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_approves_full_word (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_default_deny (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_denies (0.001s) +PASS TestUserConsentHandling.test_tty_environment_user_denies_full_word (0.001s) +SKIP TestDockerInstaller.test_can_install_docker_unavailable (0.000s) +PASS TestDockerInstaller.test_can_install_valid_dependency (0.000s) +PASS TestDockerInstaller.test_can_install_wrong_type (0.000s) +PASS TestDockerInstaller.test_get_installation_info_docker_unavailable (0.000s) +SKIP TestDockerInstaller.test_get_installation_info_image_installed (0.000s) +SKIP TestDockerInstaller.test_install_failure (0.000s) +PASS TestDockerInstaller.test_install_invalid_dependency (0.000s) +PASS TestDockerInstaller.test_install_simulation_mode (0.000s) +SKIP TestDockerInstaller.test_install_success (0.000s) +PASS TestDockerInstaller.test_installer_type (0.000s) +PASS TestDockerInstaller.test_resolve_docker_tag (0.000s) +PASS TestDockerInstaller.test_supported_schemes (0.000s) +PASS TestDockerInstaller.test_uninstall_simulation_mode (0.000s) +SKIP TestDockerInstaller.test_uninstall_success (0.000s) +PASS TestDockerInstaller.test_validate_dependency_invalid_registry (0.000s) +PASS TestDockerInstaller.test_validate_dependency_invalid_type (0.000s) +PASS TestDockerInstaller.test_validate_dependency_invalid_version_constraint (0.000s) +PASS TestDockerInstaller.test_validate_dependency_missing_name (0.000s) +PASS TestDockerInstaller.test_validate_dependency_missing_version_constraint (0.000s) +PASS TestDockerInstaller.test_validate_dependency_valid (0.000s) +PASS TestDockerInstaller.test_version_constraint_validation (0.000s) +FAIL PackageEnvironmentTests.test_add_package_environment_variable_compatibility (0.000s) + Error: AssertionError: False is not true : Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 630, in run + self._callSetUp() + ... (traceback truncated) +FAIL PackageEnvironmentTests.test_add_package_non_tty_auto_approve (0.000s) + Error: AssertionError: False is not true : Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 630, in run + self._callSetUp() + ... (traceback truncated) +FAIL PackageEnvironmentTests.test_add_package_with_dependencies_non_tty (0.000s) + Error: AssertionError: False is not true : Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 630, in run + self._callSetUp() + ... (traceback truncated) +FAIL PackageEnvironmentTests.test_environment_variable_case_variations (0.000s) + Error: AssertionError: False is not true : Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 630, in run + self._callSetUp() + ... (traceback truncated) +ERROR _ErrorHolder.setUpClass failed in TestHatchInstaller (test_hatch_installer.py) (0.000s) + Error: AssertionError: Hatching-Dev directory not found at /Users/hacker/Documents/src/CrackingShells/Hatching-Dev + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/suite.py", line 166, in _handleClassSetUp + setUpClass() + File "/Users/hacker/Documents/src/CrackingShells/Hatch/tests/test_hatch_installer.py", line 24, in setUpClass + cls.hatch_dev_path.exists() + ... (traceback truncated) +PASS BaseInstallerTests.test_installation_context_creation (0.000s) +PASS BaseInstallerTests.test_installation_context_with_config (0.000s) +PASS BaseInstallerTests.test_installation_error (0.000s) +PASS BaseInstallerTests.test_installation_result_creation (0.000s) +PASS BaseInstallerTests.test_installation_status_enum (0.000s) +PASS BaseInstallerTests.test_mock_installer_get_installation_info (0.000s) +PASS BaseInstallerTests.test_mock_installer_install (0.000s) +PASS BaseInstallerTests.test_mock_installer_interface (0.000s) +PASS BaseInstallerTests.test_mock_installer_uninstall_not_implemented (0.001s) +PASS BaseInstallerTests.test_mock_installer_validation (0.000s) +PASS BaseInstallerTests.test_progress_callback_support (0.000s) +PASS TestPythonEnvironmentManager.test_conda_env_exists (0.229s) +PASS TestPythonEnvironmentManager.test_conda_env_not_exists (0.230s) +PASS TestPythonEnvironmentManager.test_create_python_environment_already_exists (0.225s) +PASS TestPythonEnvironmentManager.test_create_python_environment_no_conda (0.225s) +PASS TestPythonEnvironmentManager.test_create_python_environment_success (0.226s) +PASS TestPythonEnvironmentManager.test_detect_conda_mamba_conda_only (0.231s) +PASS TestPythonEnvironmentManager.test_detect_conda_mamba_none_available (0.229s) +PASS TestPythonEnvironmentManager.test_detect_conda_mamba_with_mamba (0.243s) +PASS TestPythonEnvironmentManager.test_get_conda_env_name (0.240s) +PASS TestPythonEnvironmentManager.test_get_environment_activation_info_env_not_exists (0.456s) +PASS TestPythonEnvironmentManager.test_get_environment_activation_info_no_python (0.463s) +PASS TestPythonEnvironmentManager.test_get_environment_activation_info_unix (0.460s) +FAIL TestPythonEnvironmentManager.test_get_environment_activation_info_windows (0.447s) + Error: AssertionError: 'C:\\fake\\env' not found in ['C:/fake/env:C:/fake/env/Scripts:C:/fake/env/Library/bin:/Users/hacker/miniforge3/envs/forHatch-dev/bin:/Users/hacker/.nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/opt/pmk/env/global/bin:/Library/Apple/usr/bin:/Library/TeX/texbin:/Users/hacker/.nvm/versions/node/v24.13.0/bin:/Users/hacker/miniforge3/condabin:/Users/hacker/.local/bin:/Users/hacker/.cargo/bin:/Users/hacker/Documents/bin/OpenUSD/bin:/Users/hacker/.lmstudio/bin:/Users/hacker/Documents/bin/OpenUSD/bin:/Users/hacker/.lmstudio/bin'] + Traceback (most recent call last): + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 58, in testPartExecutor + yield + File "/Users/hacker/miniforge3/envs/forHatch-dev/lib/python3.12/unittest/case.py", line 634, in run + self._callTestMethod(testMethod) + ... (traceback truncated) +PASS TestPythonEnvironmentManager.test_get_preferred_executable (0.225s) +PASS TestPythonEnvironmentManager.test_get_python_executable_exists (0.235s) +PASS TestPythonEnvironmentManager.test_get_python_executable_not_exists (0.228s) +PASS TestPythonEnvironmentManager.test_get_python_executable_path_unix (0.231s) +PASS TestPythonEnvironmentManager.test_get_python_executable_path_windows (0.238s) +PASS TestPythonEnvironmentManager.test_init (0.232s) +PASS TestPythonEnvironmentManager.test_is_available_no_conda (0.470s) +PASS TestPythonEnvironmentManager.test_is_available_with_conda (0.233s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_environment_diagnostics_structure (0.258s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_get_manager_info_structure (0.240s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_interactive_unix (0.222s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_interactive_windows (0.228s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_no_python_executable (0.231s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_nonexistent_environment (0.230s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_launch_shell_with_command (0.230s) +PASS TestPythonEnvironmentManagerEnhancedFeatures.test_manager_diagnostics_structure (0.463s) +PASS TestPythonInstaller.test_can_install_python_type (0.001s) +PASS TestPythonInstaller.test_can_install_wrong_type (0.000s) +PASS TestPythonInstaller.test_install_failure (0.001s) +PASS TestPythonInstaller.test_install_simulation_mode (0.000s) +PASS TestPythonInstaller.test_install_success (0.000s) +PASS TestPythonInstaller.test_run_pip_subprocess_exception (0.001s) +PASS TestPythonInstaller.test_uninstall_failure (0.000s) +PASS TestPythonInstaller.test_uninstall_success (0.001s) +PASS TestPythonInstaller.test_validate_dependency_invalid_missing_fields (0.001s) +PASS TestPythonInstaller.test_validate_dependency_invalid_package_manager (0.000s) +PASS TestPythonInstaller.test_validate_dependency_valid (0.000s) +PASS TestInstallerRegistry.test_error_on_unknown_type (0.000s) +PASS TestInstallerRegistry.test_get_installer_instance (0.000s) +PASS TestInstallerRegistry.test_registered_types (0.000s) +PASS TestInstallerRegistry.test_registry_repr_and_len (0.000s) +PASS RegistryRetrieverTests.test_online_mode (0.434s) +PASS RegistryRetrieverTests.test_persistent_timestamp_across_cli_invocations (0.158s) +PASS RegistryRetrieverTests.test_persistent_timestamp_edge_cases (0.003s) +PASS RegistryRetrieverTests.test_registry_cache_management (0.479s) +PASS RegistryRetrieverTests.test_registry_init (0.002s) +PASS TestSystemInstaller.test_build_apt_command_automated (0.000s) +PASS TestSystemInstaller.test_build_apt_command_basic (0.000s) +PASS TestSystemInstaller.test_build_apt_command_exact_version (0.000s) +PASS TestSystemInstaller.test_can_install_apt_not_available (0.000s) +PASS TestSystemInstaller.test_can_install_unsupported_platform (0.000s) +PASS TestSystemInstaller.test_can_install_valid_dependency (0.000s) +PASS TestSystemInstaller.test_can_install_wrong_type (0.000s) +PASS TestSystemInstaller.test_install_apt_failure (0.001s) +PASS TestSystemInstaller.test_install_invalid_dependency (0.000s) +PASS TestSystemInstaller.test_install_simulation_mode (0.001s) +PASS TestSystemInstaller.test_install_success (0.001s) +PASS TestSystemInstaller.test_installer_type (0.000s) +PASS TestSystemInstaller.test_is_apt_available_false (0.000s) +PASS TestSystemInstaller.test_is_apt_available_true (0.000s) +PASS TestSystemInstaller.test_is_platform_supported_debian (0.001s) +PASS TestSystemInstaller.test_is_platform_supported_ubuntu (0.001s) +PASS TestSystemInstaller.test_is_platform_supported_unsupported (0.000s) +PASS TestSystemInstaller.test_parse_apt_error_generic (0.000s) +PASS TestSystemInstaller.test_parse_apt_error_package_not_found (0.000s) +PASS TestSystemInstaller.test_parse_apt_error_permission_denied (0.000s) +PASS TestSystemInstaller.test_simulate_installation_failure (0.000s) +PASS TestSystemInstaller.test_simulate_installation_success (0.000s) +PASS TestSystemInstaller.test_supported_schemes (0.000s) +PASS TestSystemInstaller.test_uninstall_automated (0.000s) +PASS TestSystemInstaller.test_uninstall_simulation_mode (0.000s) +PASS TestSystemInstaller.test_uninstall_success (0.000s) +PASS TestSystemInstaller.test_validate_dependency_invalid_package_manager (0.000s) +PASS TestSystemInstaller.test_validate_dependency_invalid_version_constraint (0.000s) +PASS TestSystemInstaller.test_validate_dependency_missing_name (0.000s) +PASS TestSystemInstaller.test_validate_dependency_missing_version_constraint (0.000s) +PASS TestSystemInstaller.test_validate_dependency_valid (0.000s) +PASS TestSystemInstaller.test_verify_installation_failure (0.000s) +PASS TestSystemInstaller.test_verify_installation_success (0.000s) +PASS TestAdapterProtocol.test_AP01_all_adapters_have_get_supported_fields (0.000s) +PASS TestAdapterProtocol.test_AP02_all_adapters_have_validate (0.000s) +PASS TestAdapterProtocol.test_AP03_all_adapters_have_serialize (0.000s) +PASS TestAdapterProtocol.test_AP04_serialize_never_returns_name (0.000s) +PASS TestAdapterProtocol.test_AP05_serialize_never_returns_none_values (0.000s) +PASS TestAdapterProtocol.test_AP06_get_adapter_returns_correct_type (0.000s) +PASS TestAdapterRegistry.test_AR01_registry_has_all_default_hosts (0.000s) +PASS TestAdapterRegistry.test_AR02_get_adapter_returns_correct_type (0.000s) +PASS TestAdapterRegistry.test_AR03_get_adapter_raises_for_unknown_host (0.000s) +PASS TestAdapterRegistry.test_AR04_has_adapter_returns_true_for_registered (0.000s) +PASS TestAdapterRegistry.test_AR05_has_adapter_returns_false_for_unknown (0.000s) +PASS TestAdapterRegistry.test_AR06_register_adds_new_adapter (0.000s) +PASS TestAdapterRegistry.test_AR07_register_raises_for_duplicate (0.000s) +PASS TestAdapterRegistry.test_AR08_unregister_removes_adapter (0.000s) +PASS TestAdapterRegistry.test_unregister_raises_for_unknown (0.000s) +PASS TestGlobalRegistryFunctions.test_get_adapter_raises_for_unknown (0.000s) +PASS TestGlobalRegistryFunctions.test_get_adapter_uses_default_registry (0.000s) +PASS TestGlobalRegistryFunctions.test_get_default_registry_returns_singleton (0.000s) +PASS TestMCPServerConfig.test_UM01_valid_stdio_config (0.000s) +PASS TestMCPServerConfig.test_UM02_valid_sse_config (0.000s) +PASS TestMCPServerConfig.test_UM03_valid_http_config_gemini (0.000s) +PASS TestMCPServerConfig.test_UM04_allows_command_and_url (0.000s) +PASS TestMCPServerConfig.test_UM05_reject_no_transport (0.000s) +PASS TestMCPServerConfig.test_UM06_accept_all_fields (0.000s) +PASS TestMCPServerConfig.test_UM07_extra_fields_allowed (0.000s) +PASS TestMCPServerConfig.test_command_empty_rejected (0.000s) +PASS TestMCPServerConfig.test_command_whitespace_stripped (0.000s) +PASS TestMCPServerConfig.test_serialization_roundtrip (0.000s) +PASS TestMCPServerConfig.test_url_format_validation (0.000s) +PASS TestMCPServerConfigProperties.test_is_local_server_with_command (0.000s) +PASS TestMCPServerConfigProperties.test_is_remote_server_with_httpUrl (0.000s) +PASS TestMCPServerConfigProperties.test_is_remote_server_with_url (0.000s) +=== Summary === +Total: 576 +Passed: 552 +Failed: 10 +Errors: 4 +Skipped: 10 +Success Rate: 95.8% +Exit Code: 1