fix(installer): support ssh custom-source ports

[loicduong]

What

Added support for ssh:// Git URLs with optional custom ports in installer --custom-source parsing.

Why

Self-hosted Git servers may expose SSH on non-standard ports, and users need to pass URLs like ssh://git@host:2222/path/repo.git directly without relying on SSH config aliases.
Fixes #2476.

How

• Added explicit parsing for ssh://user@host[:port]/path/repo.git URLs while preserving the original cloneUrl.
• Derived cacheKey and displayName from the SSH URL path, including the custom port in cacheKey.
• Added a filesystem-safe cache path helper so custom-port cache keys work on Windows.

Testing

Ran npm run test:urls to verify URL parsing regressions, including the new SSH custom-port cases. Also ran ESLint and Prettier checks on the changed files.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bf3c8a61-5cee-4f2f-834e-1cc594d1bf39

📥 Commits

Reviewing files that changed from the base of the PR and between 9d5739d and 87d194b.

📒 Files selected for processing (2)

• test/test-parse-source-urls.js
• tools/installer/modules/custom-module-manager.js

---

📝 Walkthrough

Walkthrough

Adds ssh://git@host[:port]/owner/repo.git URL support to parseSource() in custom-module-manager.js, introduces urlHasRepoPath() to tighten HTTP/HTTPS @ref detection, adds _getRepoCacheDir() to produce filesystem-safe cache paths from cacheKey (replacing : with __port_), wires both cloneRepo() and findModuleSource() to use it, and adds three regression tests.

Changes

SSH URL Support in Custom Module Manager

Layer / File(s)	Summary
urlHasRepoPath helper and @ref detection tightening tools/installer/modules/custom-module-manager.js	Adds urlHasRepoPath() to confirm a string parses as a URL with non-empty host and path; integrates it into parseSource()'s @ref suffix detection so HTTP/HTTPS inputs must also pass the path check before a suffix is treated as a version ref.
ssh:// URL parsing branch in parseSource() tools/installer/modules/custom-module-manager.js	Adds a dedicated ssh:// branch that uses new URL() to extract host, port, and pathname; normalizes .git suffixes; validates repo path presence; computes displayName from the last two path segments; sets cacheKey as host + cleaned path; and returns a valid URL descriptor or the standard invalid-input fallback.
_getRepoCacheDir() and callsite updates tools/installer/modules/custom-module-manager.js	Introduces _getRepoCacheDir(cacheKey) to split on / and replace : in each segment with __port_, producing filesystem-safe paths. Updates cloneRepo() and findModuleSource() to derive repoCacheDir/baseDir through this helper.
ssh:// URL regression tests test/test-parse-source-urls.js	Adds three parseSource() test cases: ssh:// with custom port (asserts port in cacheKey, displayName from last two segments), ssh:// without port, and ssh:// with @version suffix (asserts version extraction and stripped cloneUrl).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• bmad-code-org/BMAD-METHOD#2323: Adds logic to walk the ~/.bmad/cache/custom-modules/ directory to resolve url-source modules, directly coupling it to the cache layout this PR changes via _getRepoCacheDir().
• bmad-code-org/BMAD-METHOD#2344: Modifies parseSource() HTTP/HTTPS URL-handling logic, overlapping with this PR's tightening of the @ref suffix detection for those same protocols.
• bmad-code-org/BMAD-METHOD#2379: Modifies parseSource() SSH URL parsing and normalization of cacheKey/displayName, directly overlapping with the new ssh:// branch added in this PR.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: adding support for SSH custom-source URLs with custom ports in the installer.
Description check	✅ Passed	The description clearly relates to the changeset, explaining what was added, why it was needed, how it was implemented, and testing performed.
Linked Issues check	✅ Passed	The PR fully implements the requirements from issue #2476: parsing ssh://user@host[:port]/path/repo.git URLs, preserving cloneUrl, deriving cacheKey with port, displayName from path, and adding test coverage.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #2476: SSH URL parsing, cache key generation, filesystem-safe cache paths, and test coverage for the feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[augmentcode]

🤖 Augment PR Summary

Summary: This PR extends the installer’s --custom-source parsing to correctly accept ssh:// Git URLs that include non-standard SSH ports.

Changes:

• Refines @version suffix stripping so it only applies to complete HTTP(S)/SSH URLs that actually include a repo path.
• Adds explicit parsing for ssh://user@host[:port]/.../repo(.git) and derives cacheKey/displayName from the URL path.
• Normalizes SSH protocol URLs by removing query/hash before using them as cloneUrl.
• Introduces a Windows-safe cache directory mapping for cache keys that contain host:port.
• Adds URL parsing regression tests covering custom-port SSH URLs, query/hash stripping, and @version suffix handling.

Technical Notes: Cache keys for SSH protocol sources include the host:port when provided; Windows cache paths rewrite invalid : characters to keep clones filesystem-safe.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 1 suggestion posted.

Comment augment review to trigger a new review at any time.

[loicduong]

augment review

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[loicduong]

augment review

[augmentcode]

Review completed. 1 suggestion posted.

Comment augment review to trigger a new review at any time.

[loicduong]

augment review

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.