Merge branch 'main' into 514-marketplace-versioning

Author: sergio-sisternes-epam

CHANGELOG.md

@@ -24,7 +24,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Pin codex setup to `rust-v0.118.0` for security and reproducibility; update config to `wire_api = "responses"` (#663)
 - Propagate headers and environment variables through OpenCode MCP adapter with defensive copies to prevent mutation (#622)
+- Fix `apm install` hanging indefinitely when corporate firewalls silently drop SSH packets by setting `GIT_SSH_COMMAND` with `ConnectTimeout=30` (#652)
 - Fix `apm compile --target claude` silently skipping dependency instructions stored in `.github/instructions/` (#631)
+
 ### Changed
 
 - `apm marketplace browse/search/add/update` now route through the registry proxy when `PROXY_REGISTRY_URL` is set; `PROXY_REGISTRY_ONLY=1` blocks direct GitHub API calls (#506)
@@ -461,7 +463,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- **Install Script and `apm update`**: Repaired corrupted header in install.sh. Use awk instead of sed for shell subprocess compatibility. Directed shell output to terminal for password input during update process. 
+- **Install Script and `apm update`**: Repaired corrupted header in install.sh. Use awk instead of sed for shell subprocess compatibility. Directed shell output to terminal for password input during update process.
 
 ## [0.7.1] - 2025-01-22
 
@@ -503,7 +505,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **SKILL.md as first-class primitive**: meta-description of what an APM Package does for agents to read
 - **Claude Skills Installation**: Install Claude Skills directly as APM Packages
-- **Bidirectional Format Support**: 
+- **Bidirectional Format Support**:
   - APM packages → SKILL.md (for Claude target)
   - Claude Skills → .agent.md (for VSCode target)
 - **Skills Documentation**: New `docs/skills.md` guide
@@ -520,7 +522,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Target Auto-Detection**: Smart compilation based on project structure
   - `.github/` only → generates `AGENTS.md` + VSCode integration
-  - `.claude/` only → generates `CLAUDE.md` + Claude integration  
+  - `.claude/` only → generates `CLAUDE.md` + Claude integration
   - Both folders → generates all formats
   - Neither folder → generates `AGENTS.md` only (universal format)
 

docs/src/content/docs/getting-started/authentication.md

@@ -281,3 +281,9 @@ git config credential.helper              # check current helper
 git config --global credential.helper osxkeychain  # macOS
 gh auth login                              # GitHub CLI
 ```
+
+### SSH connection hangs on corporate/VPN networks
+
+When no token is available, APM tries SSH before falling back to plain HTTPS. Firewalls that silently drop SSH packets (port 22) can make `apm install` appear to hang. APM sets `GIT_SSH_COMMAND="ssh -o ConnectTimeout=30"` so SSH attempts fail within 30 seconds and the fallback proceeds to HTTPS with git credential helpers.
+
+If you already set `GIT_SSH_COMMAND` (e.g., for a custom key), APM appends `-o ConnectTimeout=30` unless `ConnectTimeout` is already present in your value.

packages/apm-guide/.apm/skills/apm-usage/authentication.md

@@ -96,3 +96,15 @@ apm install --verbose your-org/package
 # Increase git credential timeout (default 30s, max 180s)
 export APM_GIT_CREDENTIAL_TIMEOUT=120
 ```
+
+### SSH connection hangs on corporate/VPN networks
+
+APM tries SSH as a fallback when HTTPS auth is not available. On networks
+that silently drop SSH traffic (port 22), this can appear to hang. APM sets
+`GIT_SSH_COMMAND="ssh -o ConnectTimeout=30"` so SSH attempts fail within
+30 seconds and the fallback chain continues to plain HTTPS with git
+credential helpers.
+
+To override the SSH command (e.g., custom key path), set `GIT_SSH_COMMAND`
+in your environment. APM appends `-o ConnectTimeout=30` unless it finds
+`ConnectTimeout` already present in your value.

src/apm_cli/core/script_runner.py

@@ -256,7 +256,7 @@ def _auto_compile_prompts(
             compiled_prompt_files.append(prompt_file)
 
             # Read the compiled content
-            with open(compiled_path, "r") as f:
+            with open(compiled_path, "r", encoding="utf-8") as f:
                 compiled_content = f.read().strip()
 
             # Check if this is a runtime command (copilot, codex, llm) before transformation
@@ -916,7 +916,7 @@ def compile(self, prompt_file: str, params: Dict[str, str]) -> str:
         # Now ensure compiled directory exists
         self.compiled_dir.mkdir(parents=True, exist_ok=True)
 
-        with open(prompt_path, "r") as f:
+        with open(prompt_path, "r", encoding="utf-8") as f:
             content = f.read()
 
         # Parse frontmatter and content
@@ -939,7 +939,7 @@ def compile(self, prompt_file: str, params: Dict[str, str]) -> str:
         output_path = self.compiled_dir / output_name
 
         # Write compiled content
-        with open(output_path, "w") as f:
+        with open(output_path, "w", encoding="utf-8") as f:
             f.write(compiled_content)
 
         return str(output_path)