[BUG] Subdirectory packages fail on non-GitHub/ADO hosts (generic git hosts)

[shkarupa-alex]

apm install cannot install subdirectory (virtual) packages from generic git hosts (e.g. self-hosted GitLab). APM constructs an invalid clone URL by concatenating
the subdirectory path into the repository URL instead of cloning the base repository and extracting the subdirectory.

To Reproduce

1. Host a git repository on a non-GitHub, non-ADO server (e.g. GitLab CE at git.example.com)
2. Reference a subdirectory package in apm.yml:

dependencies:
apm:
  - git: https://git.example.com/my-org/my-group/my-skills.git
    path: dist/skill-a
    ref: main

3. Run apm install.

Expected behavior

APM clones my-org/my-skills.git and extracts dist/skill-a via sparse-checkout (same as GitHub).

Actual behavior

APM attempts to clone a nonexistent repo at https://git.example.com/my-org/my-skills/dist/skill-a.

Root cause

_detect_virtual_package() in reference.py:542-553:

• GitHub: min_base_segments = 2 (always owner/repo) → correct split
• Generic hosts: min_base_segments = len(path_segments) → all segments absorbed into repo_url, virtual_path never detected

Compounded by a lossy round-trip: parse_from_dict() correctly separates repo/path → str() flattens them into one string → download_package() re-parses via
parse() and loses the boundary.

Suggested fixes

A. Preserve DependencyReference through the pipeline (no str round-trip)
B. Default min_base_segments = 2 for generic hosts with opt-in for deeper paths
C. Encode the repo/path boundary in str() serialization

Workaround

None via configuration. Manual clone + copy required.

Environment (please complete the following information):

• OS: MacOS
• Python Version: 3.14.3
• APM Version: 0.8.0 (af190ac)
• VSCode Version (if relevant): no

Logs

Installing dependencies from apm.yml...
Installing APM dependencies (5)...
Using apm.lock.yaml (2 locked dependencies)

✓ github.com/anthropics/skills/skills/skill-creator
✓ github.com/vercel-labs/agent-browser/skills/agent-browser

Generated apm.lock.yaml with 2 dependencies
Installed 2 APM dependencies
No MCP dependencies found in apm.yml


── Diagnostics ──
  ✗ 3 packages failed:
    └─ ai/grandpa-s-skills/dist/brain-council — Failed to install git.example.com/ai/grandpa-s-skills/dist/brain-council#master: Failed to clone repository
ai/grandpa-s-skills/dist/brain-council using all available methods. For private repositories on git.example.com, configure SSH keys or a git credential helper. APM delegates
authentication to git for non-GitHub/ADO hosts. Last error: Cmd('git') failed due to: exit code(128)
  cmdline: git clone -v --depth=1 --branch=master -- https://git.example.com/ai/grandpa-s-skills/dist/brain-council
/var/folders/2_/n6nrjf29389cnm07z_w22_z40000gn/T/tmp46_d2g94
  stderr: 'Cloning into '/var/folders/2_/n6nrjf29389cnm07z_w22_z40000gn/T/tmp46_d2g94'...
remote: The project you were looking for could not be found or you don't have permission to view it.
fatal: repository 'https://git.example.com/ai/grandpa-s-skills/dist/brain-council.git/' not found

[sergio-sisternes-epam]

Confirmed — We've reproduced this against a self-hosted GitLab instance.

The root cause is as you described: a lossy str() → parse() round-trip in the download pipeline. parse_from_dict() correctly separates git: from path:, but __str__() flattens them into a single string. When download_package() re-parses it, _detect_virtual_package() uses min_base_segments = len(path_segments) for generic hosts, so the virtual path is never recovered.

The result is APM attempting to clone the subdirectory path as part of the repo URL:

git clone -- https://git.example.com/org/repo/dist/subdir   # actual (broken)
git clone -- https://git.example.com/org/repo               # expected

We'll fix this by preserving the structured DependencyReference through the pipeline instead of converting to string and re-parsing (your suggested fix A). Thanks for the thorough analysis — it made triage much faster.

[sergio-sisternes-epam]

Integration tested end-to-end against a self-hosted GitLab instance with a subdirectory package. With the fix in #383, apm install correctly clones the base repo and extracts the subdirectory — the exact scenario that was failing before.

✓ git.example.com/org/repo/dist/brain-council#main (cached)
  └─ 1 prompts integrated → .github/prompts/
  └─ 1 commands integrated → .claude/commands/

Installed 1 APM dependencies

[sergio-sisternes-epam]

@shkarupa-alex thank you!