[BUG] or [QUESTION] Local dependencies in shared repository

[tomdaniel-ae]

Describe the bug
We have one repository for our organisation containing all apm packages:

apm/
    _shared/
        .apm/
        apm.yml
    frontend/
        .apm/
        apm.yml # REFERENCES _shared
    backend/
        .apm/
        apm.yml # REFERENCES _shared

When installing frontend/ or backend/ into one of our projects, we get an error because it's referencing a package in the same remote repository:

Refusing to install local_path dependency './_shared' declared by remote package 'development-backend-dotnet': remote packages cannot reference paths on the consumer filesystem. Publish the dependency as a standalone package and reference it via owner/repo or marketplace handle.

To Reproduce
Steps to reproduce the behavior:

1. Create two .apm folders (e.g. _shared/ and frontend/)
2. Make sure one apm.yml references the other:

depdendencies:
  apm:
    - path: ./_shared

3. Install the frontend/ folder with apm install dev.azure.com/org/project/repo/apm/frontend
4. See the error in the terminal (mentioned above)

Expected behavior
I would expect the _shared/ apm package to be installed as well from that same remote repository.

Environment (please complete the following information):

• OS: Windows
• Python Version: 3.14.3
• APM Version: 0.16.0
• GIT Platform: Azure DevOps

Additional context
Is this expected behaviour or a bug?

If this is expected behaviour, can there be a section explaining how to achieve a setup like this? Since I can't find a clear explanation for how to set this up (besides using plugins and a complex setup to make this work).

Thanks! :)

[ivancea]

++. Discovered this issue while trying to configure a new repo with modules and dependencies.
I had to add absolute git dependencies git: <org>/<repo>#<branch>, which makes it very complicated to work with, as now:

• You can't install another branch, unless you replace every "main" branch name too
• You can't use it locally, unless you replace all references with locall ones "temporarily"

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/distribution
area/enterprise
type/feature
status/needs-design

Milestone

null

Suggested next action

Design how the resolver should detect and fetch intra-repo path dependencies for remote packages (same-remote-repo sibling resolution), answering: detection heuristic, remote-fetch mechanism per VCS host (GitHub, ADO), and lockfile representation.

Suggested issue comment

Thanks for the detailed report and the clear monorepo structure diagram, `@tomdaniel-ae`.

To answer your question directly: the current behavior is intentional as a security guardrail. When APM installs a remote package, it refuses to resolve `path:` dependencies against the consumer's filesystem -- this prevents a malicious package from referencing paths like `../../secrets` on your machine.

However, your case is different: you are referencing a sibling package within the SAME remote repository. That is "same-repo relative resolution" -- the path should be resolved against the remote repo root, not the consumer's filesystem. APM does not currently distinguish between these two cases, and that is the gap.

This is a legitimate and well-established pattern (npm/cargo workspaces, ADO monorepos), and we want to support it. However, it requires a design decision before implementation: how should the resolver detect that a `path:` reference points within the same remote repo (vs. the consumer filesystem), how should it fetch the sibling package from the remote, and how should this work across VCS hosts (GitHub vs ADO)?

We are marking this `status/needs-design`. In the meantime, the workaround is to publish `_shared` as a standalone package (with its own `apm.yml`) in a separate repo or path-accessible location. We know that is more friction than ideal -- resolving this monorepo pattern is the goal of this issue.

If you can share more about your ADO repo structure (single repo, multiple `apm.yml` files at different paths), that context will help us design the right resolution strategy. You can add it as a comment here.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The monorepo pattern (multiple packages in a single repo with sibling dependencies) is well-established in npm workspaces and cargo workspaces. The user's use case is clear and well-documented. The current guardrail is correct for consumer-filesystem paths but too broad -- it incorrectly rejects same-repo sibling references. This is a real friction point for enterprise ADO monorepo users.

Supply Chain Security Expert -- Risk-Surface Reviewer

The current guardrail ("remote packages cannot reference consumer filesystem paths") is correct and must be preserved. The enhancement needed is the ability to distinguish "same-remote-repo sibling" from "consumer filesystem path." This distinction requires the resolver to know the remote origin URL of the package being installed and to verify that the path: target resolves within that same remote repo. The security boundary is clear: only paths that resolve within the same authenticated remote origin are eligible for same-repo resolution. theme/portability (primary), area/distribution and area/enterprise as sub-themes. No theme/security because the guardrail is being refined, not relaxed.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author has author_association: NONE -- first-time contributor. The issue ends with "Thanks! :)" and asks a direct question ("Is this expected behaviour or a bug?"). Comment should answer the question directly and warmly, validate the use case, explain the current design intent without being dismissive, and give a concrete workaround while naming the path to a permanent fix.

Python Architect -- Architecture Reviewer

Fast-path triggered: the fix requires changes to the dependency resolver to detect intra-repo path references, changes to the remote-fetch pipeline to resolve siblings from the remote origin, and potentially new fields in apm.lock.yaml to record the resolution. Cross-cutting design questions: (1) how does the resolver detect that a path is within the same remote repo? (2) how does it fetch the sibling from the remote (re-use the same git clone, or a fresh fetch)? (3) how does this interact with ADO's URL scheme (dev.azure.com/org/project/repo/path)? status/needs-design is the correct outcome.

Doc Writer -- Documentation Reviewer

Not activated -- status/needs-design outcome means no doc page is needed until the design is settled; documentation will be part of the implementing PR scope.

APM CEO -- Triage Arbiter

The use case is real, common in enterprise ADO environments, and directly aligned with APM's portability theme. The current guardrail is correct but too broad. needs-design is the right gate -- the resolver needs a new detection heuristic and remote-fetch path before code can land safely. theme/portability with area/enterprise and area/distribution. No milestone until design is settled.

{
  "decision": "needs-design",
  "decision_detail": "Design must answer: (1) how the resolver detects same-remote-repo sibling paths, (2) how it fetches siblings from the remote origin per VCS host, (3) lockfile representation of resolved siblings.",
  "theme": "theme/portability",
  "areas": ["area/distribution", "area/enterprise"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Design same-repo sibling resolution: detection heuristic, remote-fetch mechanism per VCS host, and lockfile representation.",
  "comment_markdown": "Thanks for the detailed report and the clear monorepo structure diagram, `@tomdaniel-ae`.\n\nTo answer your question directly: the current behavior is intentional as a security guardrail. When APM installs a remote package, it refuses to resolve `path:` dependencies against the consumer's filesystem -- this prevents a malicious package from referencing paths like `../../secrets` on your machine.\n\nHowever, your case is different: you are referencing a sibling package within the SAME remote repository. That is \"same-repo relative resolution\" -- the path should be resolved against the remote repo root, not the consumer's filesystem. APM does not currently distinguish between these two cases, and that is the gap.\n\nThis is a legitimate and well-established pattern (npm/cargo workspaces, ADO monorepos), and we want to support it. However, it requires a design decision before implementation: how should the resolver detect that a `path:` reference points within the same remote repo (vs. the consumer filesystem), how should it fetch the sibling package from the remote, and how should this work across VCS hosts (GitHub vs ADO)?\n\nWe are marking this `status/needs-design`. In the meantime, the workaround is to publish `_shared` as a standalone package (with its own `apm.yml`) in a separate repo or path-accessible location. We know that is more friction than ideal -- resolving this monorepo pattern is the goal of this issue.\n\nIf you can share more about your ADO repo structure (single repo, multiple `apm.yml` files at different paths), that context will help us design the right resolution strategy. You can add it as a comment here."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 2.6M · ◷

[danielmeppiel]

North-star design: same-repo sibling dependencies (monorepo path: support)

Thanks @tomdaniel-ae -- this is a real, well-formed monorepo pattern, and the
diagnosis in triage is correct. Posting the autopilot design panel north-star
so implementation can proceed without re-opening the #940 path-confusion hole.

(a) Problem framing -- the #940 tension

You install a subdirectory of a remote repo (dev.azure.com/org/project/repo/apm/frontend),
and that package declares path: ./_shared, a sibling inside the same repo.

Today the resolver rejects this unconditionally. The guard lives in
APMDependencyResolver._try_load_dependency_package (src/apm_cli/deps/apm_resolver.py):
any is_local dependency whose declaring parent is remote (_is_remote_parent,
a heuristic on parent_pkg.source) is refused at ERROR severity and recorded in
_rejected_remote_local_keys so the integrate phase also skips it (#940 / PR #1111).

That guard is correct and must stay: a remote package referencing
path: ../../secrets on your filesystem is a path-confusion / escape vector.
The bug is that the guard is too broad -- it cannot tell a consumer-filesystem
path apart from a sibling that lives within the same remote clone the user already
fetched. The two cases are not the same threat.

(b) North-star approach -- "containment, not consumer paths"

Refine the guard from "reject all local paths from remote parents" to
"reject local paths that escape the originating remote repo." Allow a remote
package to reference a sibling iff the resolved path stays inside the same
cloned repo at the same ref.

This is natural because APM already has the machinery:

• Subdirectory packages exist. DependencyReference already models
  repo_url + virtual_path (is_virtual_subdirectory), which is exactly what
  .../repo/apm/frontend is.
• The whole repo is already on disk. SharedCloneCache materializes a
  bare clone of the entire repo then checks out a working tree
  (src/apm_cli/deps/shared_clone_cache.py). The sibling apm/_shared is
  already present in that same working tree -- no second fetch, no new
  network, no new credential scope.
• Relative anchoring already exists. _compute_dep_source_path /
  _effective_base_dir already anchor a relative local_path to the declaring
  package's source_path (Local relative paths in transitive deps resolve against root consumer instead of declaring package #857). For a remote subdir package that source_path
  points into the clone.

So the sibling resolves for free from the clone the user already authorized. The
north-star is to treat an in-clone sibling as a derived subdirectory package,
not as a consumer path:.

(c) Same-repo containment / security argument

The new permission is a strict subset of what the user already trusted:

1. Establish a clone-root boundary for the parent: (host, owner, repo, ref)
   plus the working-tree root from SharedCloneCache.
2. Compute candidate = (parent.source_path / local_path).resolve().
3. Containment check: candidate must be relative_to(clone_root) (the same
   primitive behind portable_relpath in utils/paths.py). If relative_to
   raises -> escape -> reject with the existing fix: resolve transitive local paths against declaring package (#857) #940 error.
4. Absolute paths: still rejected (cannot be contained by construction).
5. Cross-repo / different-origin paths: still rejected (different clone-root key).

Net: ../../secrets and /etc/... stay refused; ./_shared inside the same
authenticated repo+ref is allowed. We are tightening the predicate, not relaxing
the posture -- fail-closed remains the default for anything that cannot be proven
in-repo. Aligns with P6 (named, auditable transformation; no opaque heuristic) and
keeps the _is_remote_parent source heuristic as a fast user-facing pre-check while
the containment check is the actual boundary.

(d) Resolver / compat sketch

• Carry a remote_clone_root (+ host/owner/repo/ref identity) alongside
  parent_pkg.source_path when the parent is a remote subdirectory package.
• In the guard, branch before rejection: if parent is remote-subdir AND
  candidate is contained AND candidate/apm.yml exists -> rebind the sibling
  to a subdirectory DependencyReference (owner/repo/_shared#<parent ref>) and
  resolve it from the existing SharedCloneCache bare (dedup if multiple siblings
  reference it). Otherwise -> unchanged fix: resolve transitive local paths against declaring package (#857) #940 rejection.
• Lockfile: record the sibling by its host-portable subdir identity
  (host/owner/repo/_shared#ref), never as a consumer path:. Reproducible and
  leak-free.
• Compat: purely additive. Whole-repo remote packages (no clone root / no
  contained sibling) behave exactly as today. The author's path: ./_shared in
  apm.yml works unchanged -- no new required flag, preserving P4. Sibling inherits
  the parent's resolved commit by default, so frontend and _shared are always
  ref-consistent.

(e) Open questions for the maintainer

1. Boundary granularity: contain to the repo root, or to a declared
   workspace subtree (e.g. only under apm/)? Repo-root is simplest; workspace-root
   is stricter.
2. Surface syntax: keep overloading path: (zero author friction) or introduce
   an explicit workspace: / monorepo: source kind for P6 clarity?
3. Ref coupling: sibling always inherits the parent's pinned commit, or allow a
   per-sibling ref: override?
4. Lockfile identity: derived subdir package (owner/repo/_shared#ref) vs. a new
   sibling/workspace source type?
5. Host normalization: confirm the clone-root identity key for ADO
   (host/org/project/repo) vs. GitHub (host/owner/repo) so containment compares
   apples to apples.
6. apm.yml requirement: require the sibling to carry its own apm.yml
   (true in the example) -- and dedupe when several subdir packages in one repo
   reference the same sibling.

Panel perspectives

• devx-ux-expert (lead): path: ./_shared is the muscle memory from npm/cargo
  workspaces; it must "just work" with no new flag. Containment makes the ergonomic
  path the safe path -- P4 preserved.
• apm-ceo (lead): monorepo/ADO enterprise teams are squarely in the portability
  north-star (P5), not a niche. Ship it as a refined guard, not a special mode.
• oss-growth-hacker (lead): monorepo orgs are a high-leverage adoption segment;
  first-time contributor (author_association: NONE) -- resolving this well converts
  a team, not just a user (P7).
• supply-chain-security-expert: acceptable only because the permission is a
  subset of already-authorized trust (same clone, same ref, contained). Escape,
  absolute, and cross-origin paths stay fail-closed. This refines fix: resolve transitive local paths against declaring package (#857) #940; it does not
  reopen it.
• python-architect: reuse SharedCloneCache + Local relative paths in transitive deps resolve against root consumer instead of declaring package #857 anchoring + relative_to
  containment; rebind contained siblings to subdir DependencyReferences. Additive,
  no behavior change for existing remote packages.

--
apm-issue-autopilot design panel -- advisory north-star, no labels/close.