enhancement: `apm install --root <dir>` to target a directory other than $PWD

[srid]

Problem

apm install always writes relative to $PWD. There's no flag to redirect deployment to a different root.

This forces scratch-dir verification workflows (see #684) to physically stage every input file in the scratch tree and cd into it, rather than running apm install --root <scratch> against inputs that stay in place.

Concrete workaround in the wild

juspay/kolu runs apm install in a scratch directory as part of just ci — the motivating use case on #684. The workaround currently spans ~20 lines of a justfile recipe (agents/ai.just:49-77):

scratch=$(mktemp -d)
trap 'rm -rf "$scratch"' EXIT
rsync -a \
    --exclude='.git/' \
    --exclude='node_modules/' \
    --exclude='.direnv/' \
    --exclude='.logs/' \
    --exclude='.claude/' \
    --exclude='.codex/' \
    --exclude='.agents/' \
    --exclude='.opencode/' \
    --exclude='CLAUDE.md' \
    "$PWD/" "$scratch/"
mkdir -p "$scratch/.claude" "$scratch/.codex" "$scratch/.opencode" "$scratch/.agents"
[[ ! -e .claude/launch.json ]] || cp .claude/launch.json "$scratch/.claude/launch.json"
[[ ! -e .codex/config.toml ]] || cp .codex/config.toml "$scratch/.codex/config.toml"
(cd "$scratch" && apm install >/dev/null)
(cd "$scratch" && apm compile --target codex,opencode >/dev/null)

Every line between scratch=$(mktemp -d) and (cd "$scratch" && apm install ...) exists only because apm install can't take a target directory. With a --root flag this collapses to roughly:

scratch=$(mktemp -d)
trap 'rm -rf "$scratch"' EXIT
apm install --root "$scratch"
apm compile --root "$scratch" --target codex,opencode

Why --root (not cd-based workaround) is the right primitive

• No input duplication. The current workaround copies the entire worktree into scratch (7 exclude rules, a pair of cp fallbacks for user-owned runtime files, and mkdirs to satisfy target auto-detection). A --root flag keeps sources in place — apm.yml, the lockfile, and local-path packages all resolve from $PWD while writes land under --root.
• Uses beyond verification. Scripted setup scenarios (bootstrap scripts, fixture generation for tests, CI dry-runs) all benefit from installing into a specific directory without chdir gymnastics.
• Matches precedent. pip install --target, npm install --prefix, cargo install --root — redirecting output root is a standard package-manager affordance.

Scope

Two sub-questions the implementation will need to resolve:

1. Which paths does --root redirect? I'd expect: deployed-file writes (.claude/, .codex/, .agents/, .opencode/), apm_modules/, and the lockfile. Sources (apm.yml, local-path package roots) should continue resolving from $PWD unless a separate --manifest flag is added.
2. Interaction with apm compile. compile has the same scratch-dir use case (see the (cd "$scratch" && apm compile ...) line above). Worth applying the same flag to compile and any other command that writes to the working directory.

References

• Context: audit --ci: verify deployed file content, not just existence #684 (content verification in audit --ci — Sergio + Daniel both mentioned --root in their triage replies)
• Reference implementation of the workaround: ci(apm-sync): verify .claude/ without wiping it juspay/kolu#469
• Workaround source: agents/ai.just:49-77
• apm 0.9.2 install entry points that assume Path.cwd() / get_deploy_root(scope): src/apm_cli/commands/install.py:1191,1271,1283,1424

Environment

• apm 0.9.2 (via uvx --from git+https://github.com/juspay/apm apm — pinned to juspay fork for an unrelated fix)

[danielmeppiel]

Triaged under the new portability/security/governance roadmap (see #116).

Triage decision

accept -- the precedent is unambiguous (pip install --target,
npm install --prefix, cargo install --root) and the workaround in
juspay/kolu makes the cost of not having it concrete: roughly 20 lines
of justfile collapse to a single flag. No design ambiguity.

defer-later on milestone for now: there is no open 0.10.0 minor in
the milestone list, and this is feature work rather than a patch fix.
It will land in the next minor release window.

Proposed labels

theme/portability
area/cli
type/feature
status/accepted

Milestone

null -- promote to the next open minor (likely 0.10.0) once that
milestone exists. Tracking in the roadmap discussion.

Suggested next action

If you (or anyone reading) wants to take this, the entry points to
modify are already named in the issue body
(src/apm_cli/commands/install.py:1191,1271,1283,1424). Open a draft
PR; the design call we will need to make in review is whether
apm.yml and lockfile reads also redirect to --root or stay in
$PWD (your "Sources continue resolving from $PWD" framing is the
right default).

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This is exactly the "surprise nobody" change. --root reads
identically across pip, cargo, and npm-with---prefix. The
issue author also calls out that apm compile needs the same flag --
that is correct; both commands write to the working directory and
both should accept --root. Discoverability via apm install --help
is mandatory.

Supply Chain Security Expert -- Risk-Surface Reviewer

Touches area/cli (and indirectly area/distribution via where
files land). Any user-supplied --root value must flow through
path_security.validate_path_segments + ensure_path_within
checks. Lockfile writes redirected by --root must still produce
deterministic, bit-identical content. No new auth surface.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author has 7 prior interactions on microsoft/apm.

APM CEO -- Triage Arbiter

Strong fit for the Portable pillar. The juspay/kolu workaround is the
kind of evidence we want for prioritization. Ratifying accept,
primary theme/portability, status/accepted, no milestone yet
(deferred to next minor).

[srid]

If you (or anyone reading) wants to take this

I'l give it a try.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/cli
area/docs-site
type/feature
status/accepted
priority/low

Milestone

0.9.4

Suggested next action

Add a --root <dir> flag to apm install that redirects deployed-file writes, apm_modules/, and the lockfile path, while keeping apm.yml and local-path package resolution anchored to $PWD.

Suggested issue comment

Thanks for the concrete workaround evidence from juspay/kolu -- the 20-line justfile recipe is exactly the kind of friction `--root` eliminates.

The feature is accepted. `pip install --target`, `npm install --prefix`, and `cargo install --root` establish clear precedent for output-root redirection as a standard package-manager affordance. The scope is well-defined: writes (deployed files, `apm_modules/`, lockfile) redirect to `--root`; sources (`apm.yml`, local-path package roots) stay anchored to `$PWD`.

The implementing PR will need to thread a `deploy_root` parameter through the install phases (the `Path.cwd()` / `get_deploy_root()` calls at `install.py:1191,1271,1283,1424` are the sites). Applying the same flag to `apm compile` is worth doing in the same PR given the identical scratch-dir use case.

Path security note: the `--root` argument must be validated with `ensure_path_within` after resolution to prevent traversal if the value comes from a config file rather than the CLI directly.

Accepting for 0.9.4 at low priority (workaround exists).

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Clear friction point: scratch-dir verification workflows require physical file staging and cd gymnastics because apm install always writes to $PWD. The --root <dir> flag eliminates this with a well-precedented interface (pip install --target, npm install --prefix, cargo install --root). The workaround in juspay/kolu (20-line justfile recipe, 7 rsync exclude rules) is concrete evidence of real user pain. The scope is well-defined in the issue body.

Supply Chain Security Expert -- Risk-Surface Reviewer

A --root flag redirecting deploy outputs is a path security concern if the value originates from a config file or untrusted input. ensure_path_within must guard the resolved --root path. No theme/security needed, but the implementing PR must use path_security.py guards as specified in the path safety rule. theme/portability applies -- this is a standard portability/scripting affordance.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- srid is a CONTRIBUTOR with prior interactions; standard tone is appropriate.

Python Architect -- Architecture Reviewer

--root needs to thread through: install phases, compile, and any command that calls get_deploy_root(). The current codebase has Path.cwd() assumptions at install.py:1191,1271,1283,1424. The design is clear (introduce a deploy_root parameter propagated from the CLI flag); the implementation needs care to thread it through all the right places. The issue body already answers the key scoping questions (sources stay at $PWD, writes go to --root). status/accepted is appropriate -- no design gate needed.

Doc Writer -- Documentation Reviewer

The CLI reference docs need to mention the --root flag for apm install and (if included in scope) apm compile. area/docs-site is warranted as a secondary label. The suggested comment wording is clear and grounded in package-manager vocabulary.

APM CEO -- Triage Arbiter

Clear accept at priority/low. The --root flag is a clean, precedent-backed addition with a concrete real-world use case. Design is sufficiently specified in the issue body. Milestone 0.9.4 is appropriate. Path security guard is a mandatory implementing PR requirement (mentioned in the comment for the implementer).

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Add --root <dir> flag to apm install redirecting deployed-file writes, apm_modules/, and lockfile path while keeping apm.yml resolution anchored to $PWD.",
  "comment_markdown": "Thanks for the concrete workaround evidence from juspay/kolu -- the 20-line justfile recipe is exactly the friction `--root` eliminates.\n\nAccepted. `pip install --target`, `npm install --prefix`, `cargo install --root` establish clear precedent. The implementing PR threads `deploy_root` through the install phases (`install.py:1191,1271,1283,1424`) and applies the same flag to `apm compile`. Path security: `ensure_path_within` must guard the `--root` argument after resolution.\n\nAccepting for 0.9.4 at low priority (workaround exists)."
}

---

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 · ● 1.6M · ◷