Skip to content

fix(scope): make APM_HOME the single root for APM-owned user state - #3614

Merged
Daniel Meppiel (danielmeppiel) merged 23 commits into
mainfrom
danielmeppiel-apm-home-user-root-2884
Nov 12, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 23 commits into
mainfrom
danielmeppiel-apm-home-user-root-2884

Conversation

@danielmeppiel

Copy link
Copy Markdown
Collaborator

Description

TL;DR

APM_HOME becomes the single root for APM-owned user state. The global apm.yml, apm.lock.yaml, apm_modules/, config.json, marketplace registrations, lifecycle trust/logs/lock and deployment receipts all resolve through one function, apm_cli.core.scope.get_apm_home(). Unset (or empty) keeps today's ~/.apm byte-for-byte; files deployed to harness directories do not move. This PR rebuilds Ching Wei Kang (@WilliamK112)'s work from closed PR #2967, keeping his authorship. It is also the prerequisite resolver for #3006.

Note

Credit: the core change is Ching Wei Kang (@WilliamK112)'s commit, cherry-picked with his authorship from WilliamK112/apm@codex/apm-home-2884 (closed PR #2967; maintainers could not push to the fork). The follow-up commits complete the record's Done-when list and merge current main. Ching Wei Kang (@WilliamK112) please review.

Important

For #3006 (declarative marketplaces in the user manifest): call from apm_cli.core.scope import get_apm_home. The user manifest is get_manifest_path(InstallScope.USER), which is get_apm_home() / "apm.yml". Do not read APM_HOME directly: the architecture guard registry_delegation.apm_home_resolution rejects any other "APM_HOME" literal under src/.

Local preflight skipped by maintainer instruction (2026-11-12); CI is the gate.

Problem (WHY)

  • Lifecycle processing read $APM_HOME/apm.yml while install/update/lock/deps -g read ~/.apm/apm.yml, so one process could pick two different user manifests ([BUG] Document and align APM_HOME behavior for global user state #2884).
  • config.json, marketplaces.json, the marketplace cache, the lifecycle lock and deployment receipts were hardcoded to ~/.apm. An "isolated" run with APM_HOME=/tmp/x still read and wrote the real home.
  • [!] Five modules each re-derived the root (os.environ.get("APM_HOME") or Path.home() / ".apm"), so drift was a matter of time.

Why these matter: the record's Done-when requires that "every global command … reads and writes only under it" and that "two different APM_HOME values do not interfere" (scope record). Repo rule: one authority per durable decision, guarded by a regression test plus a static boundary check (.github/instructions/architecture.instructions.md).

Approach (WHAT)

# Fix
1 Add get_apm_home() to core/scope.py: APM_HOME if non-empty, else ~/.apm. get_apm_dir/get_manifest_path/get_lockfile_dir/ensure_user_dirs(USER) delegate to it.
2 Route config, lifecycle manifest/trust/log, lifecycle lock, registry workspace manifest, legacy approvals and deployment receipts through it. Marketplace registrations and cache follow via config.CONFIG_DIR.
3 User-facing messages and help text print the resolved path, or say "APM user home", instead of a literal ~/.apm.
4 Add architecture guard registry_delegation.apm_home_resolution: one owner, one env lookup, pinned consumers, no "APM_HOME" literal anywhere else. Includes a mutation case.
5 Docs: one authoritative contract in the env-var reference (paths, precedence, isolation, migration, out-of-contract paths). Install/update/lock/deps/lifecycle/config pages link back to it. Also updates apm-guide and the CHANGELOG.

Implementation (HOW)

  • src/apm_cli/core/scope.py (William): the canonical resolver. Deploy roots (get_deploy_root, get_source_root) still return the OS home, so the code itself keeps APM metadata and target files apart.
  • src/apm_cli/config.py (William): CONFIG_DIR = os.fspath(get_apm_home()). It is resolved once at import, which matches "APM reads APM_HOME once at process start". Tests that monkeypatch CONFIG_DIR keep working.
  • src/apm_cli/core/deployment_ledger.py (follow-up): receipts move to $APM_HOME/deployment-receipts/. The containment/symlink check is anchored at get_apm_home().parent, which is still $HOME by default (parity). The .apm-local/installation identity stays at the deploy root; see Trade-offs.
  • install/locking.py, core/lifecycle_scripts.py, core/script_trust.py, core/script_executors.py, deps/registry/*, security/executables.py (William): each one is now a one-line delegate to get_apm_home().
  • scripts/architecture_linter/checks/registry_owner_guards.py + .apm/architecture/owners/core-runtime.json: the new owner guard. Merge conflicts with main's newer guards were resolved during the cherry-pick (both kept).
  • tests/conftest.py: drops a developer's APM_HOME at session start, so the suite stays hermetic.

Diagrams

Legend: one resolver feeds every APM-owned path (left). Target deployment (right) never consults it. The two families do not fall back to each other.

flowchart LR
    ENV["APM_HOME env, read once"] --> R["core/scope.py get_apm_home()"]
    DEF["unset or empty"] -->|"fallback ~/.apm"| R
    R --> M["apm.yml, apm.lock.yaml, apm_modules/"]
    R --> C["config.json, marketplaces.json, cache/marketplace/"]
    R --> L["scripts-trust.json, logs/, .apm-lifecycle.lock"]
    R --> D["deployment-receipts/"]
    T["CLAUDE_CONFIG_DIR, CODEX_HOME, HERMES_HOME"] --> TD["target deploy dirs"]
    H["OS home"] -->|"fallback"| TD
    H --> ID[".apm-local/ identity for --global"]
Loading

Trade-offs

  • The --global .apm-local/ identity stays in the OS home. It identifies the deployment root (inode and birth time of $HOME), not APM metadata. install.md already documents it as living "in your home directory for --global". Moving it under APM_HOME would change parity when unset. The env-var reference lists this explicitly as out of contract.
  • Runtimes (~/.apm/runtimes/) unchanged. They are not in the record's list, and the shell installers hardcode that path. This is documented as out of contract.
  • config.CONFIG_DIR is import-time, not live. Production CLI processes read env once. Making it dynamic would break about 70 test files that monkeypatch the constant. In-process callers that need the live value ([FEATURE] Global marketplace directories for enterprise-wide discovery #3006) call get_apm_home().
  • No automatic migration. Out of scope per the record. The docs tell users to copy ~/.apm themselves.
  • User-scope local .apm/ primitives still resolve from the OS home source root (undocumented, incidental behavior; get_source_root(USER) is unchanged).

Benefits

  1. With APM_HOME set, install/update/uninstall/deps/lock -g, config, marketplace and lifecycle write nothing under ~/.apm. The subprocess test asserts that the OS home holds only .apm-local/ and the update-check cache.
  2. Two APM_HOME values are fully independent across config, manifest, lockfile, marketplaces, trust and uninstall.
  3. Unset and empty APM_HOME produce the same ~/.apm layout as before, receipts included.
  4. A re-derivation of the root anywhere in src/ fails the Lint job via the owner guard.
  5. [FEATURE] Global marketplace directories for enterprise-wide discovery #3006 gets one documented import: apm_cli.core.scope.get_apm_home.

Issue and approved scope

Issue: Fixes #2884

Human scope-approval comment: #2884 (comment) (approve, area project, review contact Daniel Meppiel (@danielmeppiel)). scripts/governance/eligibility.cjs from trusted main returned record-present.

Does this PR complete the issue, or what remains? It completes the record's Done-when. Out of scope per the record: harness deployment destinations, new env vars, automatic migration, project-scope changes, and #3006 itself.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass (targeted files; CI runs the full suites)
  • Added tests for new functionality (if applicable)

Scenario evidence

# Scenario (user promise) Principle(s) Test(s) proving it Type
1 With APM_HOME=A, config, install -g, deps list -g, lock -g, marketplace list, lifecycle trust and uninstall -g use only A. A second home B never sees A's state, and nothing lands in ~/.apm. DevX, Governed by policy tests/integration/test_apm_home_isolation.py::test_two_apm_homes_do_not_interfere (regression-trap for #2884) integration (real binary)
2 Unset APM_HOME keeps the exact ~/.apm layout, including receipts DevX tests/integration/test_apm_home_isolation.py::test_unset_apm_home_keeps_the_default_layout integration
3 APM_HOME="" behaves as unset DevX …::test_empty_apm_home_behaves_as_unset
tests/unit/core/test_scope.py::…::test_empty_apm_home_uses_default
integration, unit
4 APM_HOME isolates metadata but Claude files still deploy to CLAUDE_CONFIG_DIR Multi-harness support tests/integration/test_compile_global.py::test_apm_home_isolates_metadata_without_redirecting_target_deployment
tests/unit/core/test_scope.py::test_apm_home_does_not_redirect_target_deployment
integration, unit
5 Receipts follow APM_HOME, keep symlink/containment protection, and stay at ~/.apm when unset Secure by default tests/unit/test_deployment_materialization_receipts.py::test_receipts_live_under_apm_home_while_identity_stays_at_root, ::test_unset_apm_home_keeps_receipts_under_home_dot_apm, ::test_symlinked_evidence_is_rejected_without_touching_referent unit
6 Lifecycle lock and config resolve under APM_HOME in a fresh process DevX tests/unit/install/test_workspace_locking.py::test_lifecycle_lock_honors_apm_home
tests/unit/test_config.py::test_apm_home_selects_config_path_in_fresh_process
unit
7 No module can re-read APM_HOME outside the owner Governed by policy tests/integration/test_architecture_apm_home.py (3 tests) and the registry-delegation-apm-home-resolution mutation case integration
Validation commands and results

Mutation-break (each reverted line turned the suite red, then was restored):

scope.py   APM_HOME lookup -> None            : 9 failed
config.py  CONFIG_DIR -> expanduser(~/.apm)   : 1 failed
deployment_ledger.py receipts -> ~/.apm       : 1 failed
locking.py lifecycle lock -> ~/.apm           : 1 failed

Post-merge with origin/main:

$ .venv/bin/python -m pytest -q -p no:xdist tests/unit/core/test_scope.py tests/unit/test_config.py \
    tests/unit/test_deployment_materialization_receipts.py tests/unit/install/test_workspace_locking.py \
    tests/unit/scripts/test_architecture_runner.py tests/integration/test_architecture_apm_home.py \
    tests/integration/test_apm_home_isolation.py tests/integration/test_compile_global.py
282 passed, 1 skipped
$ APM_BINARY_PATH=.venv/bin/apm .venv/bin/python -m pytest -q -p no:xdist tests/integration/test_apm_home_isolation.py
3 passed
$ .venv/bin/python -m pytest -q -p no:xdist tests/unit/install/test_pipeline_ownership_snapshot.py \
    tests/unit/install/phases/test_cleanup_phase.py tests/unit/test_deployment_materialization_receipts.py
123 passed
$ .venv/bin/python -m pytest -q -p no:xdist tests/integration/test_architecture_owner_rule_mutations.py \
    -k "apm_home or covers_every or case_order or report_nothing"
passed (6 + 3)

Lint mirror: ruff check passed, ruff format --check passed, pylint R0801 scored 10.00/10, lint-auth-signals.sh was clean, lint_architecture_boundaries.py --root . exited 0, and no source file exceeds 2100 lines.

How to test

  • export APM_HOME="$(mktemp -d)/apm"; apm config set target claude; apm install -g <org/pkg>: everything lands under $APM_HOME, and ~/.apm is untouched.
  • APM_HOME=/tmp/other apm deps list -g: the package from the previous step is not listed.
  • unset APM_HOME; apm deps list -g: your normal ~/.apm state is shown, unchanged.
  • Read the contract under "APM_HOME path contract" in docs/src/content/docs/reference/environment-variables.md.

Spec conformance (OpenAPM v0.1)

  • Spec edit
  • Manifest edit
  • Test edit
  • CONFORMANCE.{md,json} regenerated
  • N/A -- this PR does not change OpenAPM-observable behaviour (user-scope metadata location is CLI configuration, not a manifest or lockfile contract).

Co-authored-by: Ching-Wei Kang 164879897+WilliamK112@users.noreply.github.com
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

Centralize APM-owned user metadata under APM_HOME while keeping target deployment paths independent. Document and test the contract across package, config, lifecycle, and architecture boundaries.
…2884)

Finish the APM_HOME single-root contract on top of the cherry-picked
change from @WilliamK112 (closed PR #2967):

- Deployment receipts move under get_apm_home(); the deploy-root
  .apm-local identity stays with the deployment root, like target files.
- The architecture guard also pins the deployment ledger consumer.
- Tests: subprocess isolation (two APM_HOME values, every global
  command family) and parity (unset/empty == ~/.apm); conftest drops a
  developer APM_HOME so the suite stays hermetic.
- Docs: env-var contract lists marketplace registrations, receipts,
  lock, precedence, migration and the out-of-contract paths; apm-guide
  and CHANGELOG updated (entry moved to Unreleased).

Co-authored-by: Ching-Wei Kang <164879897+WilliamK112@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…e-user-root-2884

# Conflicts:
#	docs/src/content/docs/reference/cli/config.md
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 12, 2026 13:54
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Different APM_HOME values allow operations on the same project to acquire separate lifecycle locks, enabling a failed install’s rollback to overwrite another operation’s manifest changes.

2 open issues
What changed in this PR

This PR centralizes APM-owned user metadata under get_apm_home(), addressing #2884 and providing the resolver needed by #3006. It preserves ~/.apm as the default and keeps target deployment destinations separate.

Changes:

  • Routes configuration, global package state, lifecycle state, and deployment receipts through the shared resolver.
  • Adds isolation tests and an architecture guard against independent root resolution.
  • Updates CLI messages, documentation, and the shipped APM guide to describe the path contract.
File Description
tests/​unit/​test_outdated_command.py Expects the resolved path in diagnostics.
tests/​unit/​test_deployment_materialization_receipts.py Tests receipt relocation and default parity.
tests/​unit/​test_config.py Tests configuration isolation in a fresh process.
tests/​unit/​scripts/​test_architecture_runner.py Registers the expected architecture rule.
tests/​unit/​install/​test_workspace_locking.py Tests the overridden lifecycle lock path.
tests/​unit/​core/​test_scope.py Tests metadata paths and deployment separation.
tests/​unit/​compilation/​test_compile_global_flag.py Updates manifest-path diagnostic assertions.
tests/​integration/​test_compile_global.py Tests metadata and target-directory separation.
tests/​integration/​test_architecture_owner_rule_mutations.py Adds a resolver mutation case.
tests/​integration/​test_architecture_apm_home.py Tests resolver ownership enforcement.
tests/​integration/​test_apm_home_isolation.py Exercises isolation and fallback through CLI processes.
tests/​conftest.py Clears inherited APM_HOME during test setup.
src/​apm_cli/​security/​executables.py Relocates legacy approval lookup.
src/​apm_cli/​install/​phases/​integrate.py Reports the configured approval-store path.
src/​apm_cli/​install/​manifest_helpers.py Displays the selected user metadata root.
src/​apm_cli/​install/​locking.py Moves lifecycle locking under the selected root.
src/​apm_cli/​deps/​registry/​config_loader.py Uses the canonical user manifest path.
src/​apm_cli/​deps/​registry/​auth.py Updates the configuration remediation path.
src/​apm_cli/​core/​script_trust.py Delegates trust-store path resolution.
src/​apm_cli/​core/​script_executors.py Delegates lifecycle log path resolution.
src/​apm_cli/​core/​scope.py Defines the canonical user metadata resolver.
src/​apm_cli/​core/​lifecycle_scripts.py Delegates user lifecycle manifest resolution.
src/​apm_cli/​core/​deployment_ledger.py Relocates receipts while retaining deployment identity.
src/​apm_cli/​config.py Derives configuration paths from the resolver.
src/​apm_cli/​commands/​view.py Updates global-scope help text.
src/​apm_cli/​commands/​update.py Updates help and missing-manifest diagnostics.
src/​apm_cli/​commands/​uninstall/​cli.py Updates help and user-scope progress output.
src/​apm_cli/​commands/​outdated.py Reports the selected metadata directory.
src/​apm_cli/​commands/​mcp.py Updates global installation help.
src/​apm_cli/​commands/​lock.py Updates help and missing-manifest diagnostics.
src/​apm_cli/​commands/​lifecycle.py Reports the resolved script-log path.
src/​apm_cli/​commands/​install.py Explains metadata versus deployment in help.
src/​apm_cli/​commands/​discover.py Updates user-manifest help text.
src/​apm_cli/​commands/​deps/​why.py Updates user lockfile help text.
src/​apm_cli/​commands/​deps/​cli.py Updates global help and path diagnostics.
src/​apm_cli/​commands/​config.py Reports the configured persistence path.
src/​apm_cli/​commands/​compile/​cli.py Updates manifest provenance and global help.
src/​apm_cli/​commands/​approve.py Uses the configured store label and revised help.
scripts/​architecture_linter/​checks/​registry_owner_guards.py Enforces canonical resolver ownership and delegation.
packages/​apm-guide/​.apm/​skills/​apm-usage/​governance.md Updates the user configuration location.
packages/​apm-guide/​.apm/​skills/​apm-usage/​commands.md Documents metadata scope and exclusions.
docs/​src/​content/​docs/​reference/​environment-variables.md Defines the authoritative APM_HOME contract.
docs/​src/​content/​docs/​reference/​cli/​view.md Documents overridden package metadata paths.
docs/​src/​content/​docs/​reference/​cli/​update.md Documents global metadata and deployment separation.
docs/​src/​content/​docs/​reference/​cli/​uninstall.md Updates user manifest and cleanup descriptions.
docs/​src/​content/​docs/​reference/​cli/​self-update.md Clarifies the preserved configuration location.
docs/​src/​content/​docs/​reference/​cli/​publish.md Updates the registry credential-store path.
docs/​src/​content/​docs/​reference/​cli/​outdated.md Updates global dependency locations.
docs/​src/​content/​docs/​reference/​cli/​mcp.md Separates user metadata from runtime configuration.
docs/​src/​content/​docs/​reference/​cli/​lock.md Updates user manifest and lockfile locations.
docs/​src/​content/​docs/​reference/​cli/​lifecycle.md Updates trust/log paths and links the contract.
docs/​src/​content/​docs/​reference/​cli/​install.md Updates metadata, dry-run, and receipt documentation.
docs/​src/​content/​docs/​reference/​cli/​experimental.md Updates feature-flag storage paths.
docs/​src/​content/​docs/​reference/​cli/​deps.md Updates global dependency state paths.
docs/​src/​content/​docs/​reference/​cli/​deny.md Updates the user denial-store location.
docs/​src/​content/​docs/​reference/​cli/​config.md Updates configuration paths and precedence examples.
docs/​src/​content/​docs/​reference/​cli/​compile.md Documents overridden inputs and separate outputs.
docs/​src/​content/​docs/​reference/​cli/​approve.md Updates approval storage and legacy migration paths.
docs/​src/​content/​docs/​enterprise/​registry-proxy.md Revises marketplace registration and cache locations.
CHANGELOG.md Records the fix and adds a historical GitLab entry.
.apm/​architecture/​owners/​core-runtime.json Registers metadata-root ownership and its guard.

Review effort: Balanced

Comment thread src/apm_cli/install/locking.py Resolved
Comment thread src/apm_cli/core/scope.py Resolved
Resolve conflicts with #3633 (forwarded apm install options) and #3630 (bootstrap author), keeping the APM_HOME wording.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
apm lock -g and apm update -g chdir into the APM home, so a relative APM_HOME such as 'metadata' resolved to metadata/metadata on later lookups and split the manifest from its lockfile, modules and config. get_apm_home() now expands a leading ~ and anchors a relative value once against the working directory captured at import. Addresses Copilot inline on src/apm_cli/core/scope.py:54 (#2884).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Moving the lifecycle lock under APM_HOME let processes with different homes mutate the same project or harness directories at once, so a failed install's rollback could overwrite another operation's manifest. acquire_lifecycle_lock() now takes the OS-user deployment-root lock in ~/.apm-local/ (named by the deployment owner) before the APM_HOME metadata lock and releases both together; unset APM_HOME keeps the ~/.apm layout. Adds a cross-home contention regression and updates home write-set snapshots and the pre-compile lock probe. Addresses Copilot inline on src/apm_cli/install/locking.py:44 (#2884).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The APM_HOME path contract now states that ~ is expanded, a relative value resolves against the start directory, and ~/.apm-local/.apm-lifecycle.lock serializes commands across APM_HOME values. Mirrors the change in apm-guide and the CHANGELOG entry (#2884).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_with_followups

APM_HOME as the single relocatable root for user state is architecturally sound, well-tested, and ready to unblock the marketplace resolver prerequisite chain.

panel-mode=full; personas=python-architect,test-coverage-expert,doc-writer,devx-ux-expert,performance-expert,supply-chain-security-expert,auth-expert,apm-ceo

cc Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

Seven panelists converge: this PR delivers on the apm-scope:v1 done-when with textbook single-owner discipline, a sound two-lock composite that restores cross-home deployment-root serialization (the Copilot inline finding was folded), and docs that define the APM_HOME contract once with precedence, isolation, and explicit out-of-contract items. Auth credential paths route cleanly through get_apm_home() with no leakage, and the supply-chain trust store, receipts, and approval machinery relocate without losing their integrity invariants. The architecture linter guard (registry_delegation.apm_home_resolution) is a defensibility asset: it makes the single-owner contract machine-enforceable, raising the cost for any incumbent to replicate APM's relocatable-root guarantee.

The one finding that rises above opinion is the test-coverage-expert's evidence-backed gap: the new deployment-root lock at ~/.apm-local/ lacks a direct symlink-rejection test. The metadata-path symlink test exists, but it covers a different base (get_apm_home()), not Path.home(). Because symlink rejection on a lock path is a secure-by-default load-bearing guard, this missing test inherits the criticality of the promise it protects and is the highest-signal follow-up to track. The remaining recommended findings -- a stray CHANGELOG hunk from the #2967 cherry-pick, two hardcoded ~/.apm/config.json references in approve/deny --help, and an install.md line that still names ~/.apm/ as the canonical root -- are in-scope cleanup that the merge-worker can fold before landing without scope creep.

The python-architect and performance-expert independently flagged locking.py's top-level import of deployment_ledger for a single string constant; moving LOCAL_STATE_DIR to core/scope.py is the right long-term call but is a refactor best tracked as a follow-up to avoid churn in this already-large diff.

Dissent. python-architect rated the LOCAL_STATE_DIR import coupling as recommended; performance-expert rated the same import as nit (~5ms startup). I side with recommended on substance (import-chain coupling is an architecture concern, not just perf) but agree it is post-merge cleanup, not a hold.

Aligned with: Secure by default: Two-lock composite with symlink rejection on both paths preserves deployment-root serialization; one missing symlink test for the new lock is the top follow-up. Governed by policy: APM_HOME contract documented with precedence, isolation, out-of-contract items; architecture linter guard enforces single-owner resolution at CI time. Multi-harness / multi-host: Deploy roots remain OS-home-anchored; APM_HOME controls only metadata and trust state. Pragmatic as npm: Single relocatable env-var root follows the npm/cargo/XDG convention users expect; unset defaults to ~/.apm with full parity.

Panel summary

Persona B R N Takeaway
Python Architect 0 1 2 Single-owner discipline is textbook; two-lock composite is sound; move LOCAL_STATE_DIR out of deployment_ledger to avoid eager import chain in every decorated command.
Test Coverage Expert 0 1 0 Strong coverage across all done-when promises; one gap: new deployment-root lock at ~/.apm-local/ lacks a symlink-rejection test.
Doc Writer 0 2 1 Done-when docs coverage met; remove stray CHANGELOG 0.31.0 hunk, fix install.md drift, link the contract from CLI pages.
DevX UX Expert 0 1 2 Help text and error wording correctly resolve APM_HOME; approve/deny docstrings still hardcode ~/.apm/config.json in user-visible --help.
Performance Expert 0 0 1 No hot-path regression; one nit: locking.py top-level import of deployment_ledger solely for a string constant adds ~5ms startup on every mutating command.
Supply Chain Security Expert 0 0 1 APM_HOME relocation preserves trust-store, receipt, approval, and locking integrity invariants.
Auth Expert 0 0 1 Token resolution chains untouched; credential config paths route through get_apm_home(); no credential leakage. Ship.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 5 follow-ups

  1. [Test Coverage Expert] Add a symlink-rejection unit test for the deployment-root lock at ~/.apm-local/.apm-lifecycle.lock -- Evidence outcome=missing on a secure-by-default surface; the metadata-lock symlink test covers a different base path.
  2. [Doc Writer] Remove the stray '### Fixed' hunk inside the released [0.31.0] CHANGELOG section (cherry-pick artifact from fix: honor APM_HOME for global user state #2967) -- Violates changelog.instructions.md and ships an out-of-scope entry in a released block.
  3. [DevX UX Expert] Replace hardcoded ~/.apm/config.json in approve_cmd and deny_cmd Click docstrings with resolved path or generic wording -- Click renders docstrings as --help text; users with APM_HOME set see a stale path. Foldable.
  4. [Doc Writer] Fix install.md line 283 to reference the APM_HOME contract page instead of hardcoding ~/.apm/ as canonical root -- Done-when requires install docs to state the contract correctly; a one-line link swap.
  5. [Python Architect] Move LOCAL_STATE_DIR constant from deployment_ledger.py to core/scope.py so locking.py avoids the full ledger import chain -- Reduces ~20 command modules' import-time coupling; performance-expert independently confirmed ~5ms startup cost. Best as a post-merge refactor.

Architecture

classDiagram
    direction LR
    class ScopeModule {
        <<CanonicalOwner>>
        +get_apm_home() Path
        +get_apm_dir(scope) Path
        +get_manifest_path(scope) Path
        +get_lockfile_dir(scope) Path
        +ensure_user_dirs() Path
    }
    class InstallScope {
        <<Enum>>
        PROJECT
        USER
    }
    class ConfigModule {
        <<FrozenAtImport>>
        +CONFIG_DIR str
        +CONFIG_FILE str
    }
    class LifecycleLockHandle {
        <<Composite>>
        -_deployment FileLock
        -_metadata FileLock
        +lock_file str
        +is_locked bool
        +release() void
    }
    class LockingModule {
        <<Module>>
        +lifecycle_lock() FileLock
        +deployment_root_lock() FileLock
        +acquire_lifecycle_lock() LifecycleLockHandle
    }
    class DeploymentMaterializationSession {
        <<Session>>
        +state_path Path
        +identity_path Path
        -_receipts_base Path
    }
    class ArchGuardApmHome {
        <<StaticAnalysis>>
        +check_apm_home_resolution() Violations
    }
    ScopeModule *-- InstallScope : scopes
    ConfigModule ..> ScopeModule : import-time get_apm_home()
    LockingModule ..> ScopeModule : get_apm_home() for metadata lock
    LockingModule *-- LifecycleLockHandle : creates
    DeploymentMaterializationSession ..> ScopeModule : get_apm_home() for receipts
    LockingModule ..> DeploymentMaterializationSession : LOCAL_STATE_DIR
    ArchGuardApmHome ..> ScopeModule : enforces single owner
    class ScopeModule:::touched
    class LifecycleLockHandle:::touched
    class LockingModule:::touched
    class DeploymentMaterializationSession:::touched
    class ConfigModule:::touched
    class ArchGuardApmHome:::touched
    classDef touched fill:#fff3b0,stroke:#d47600
Loading
flowchart TD
    A["CLI command e.g. apm install -g"] --> B["serialized_lifecycle (install/locking.py)"]
    B --> C["acquire_lifecycle_lock()"]
    C --> D["deployment_root_lock() ~/.apm-local/.apm-lifecycle.lock"]
    D --> G{"deployment lock acquired?"}
    G -- yes --> H["lifecycle_lock() APM_HOME/.apm-lifecycle.lock"]
    G -- timeout --> I["LifecycleBusyError"]
    H --> L{"metadata lock acquired?"}
    L -- yes --> M["LifecycleLockHandle: both locks held"]
    L -- timeout --> N["release deployment lock, LifecycleBusyError"]
    M --> O["get_apm_home() core/scope.py"]
    O --> P{"APM_HOME set and non-empty?"}
    P -- yes --> Q["expanduser, anchor relative to startup cwd"]
    P -- no --> R["Path.home() / .apm"]
    Q --> S["command body reads/writes APM_HOME"]
    R --> S
    S --> T["release metadata lock, then deployment-root lock"]
Loading

Recommendation

All seven panelists signal ship; no blocking findings. The merge-worker should fold the three in-scope cleanups (stray CHANGELOG hunk, approve/deny --help paths, install.md reference) before landing, and the deployment-root lock symlink test should be tracked as the first post-merge follow-up since it guards a secure-by-default surface. The PR unblocks the marketplace resolver chain (#3006 / PR #3610) and should land once CI greens.


Full per-persona findings

Python Architect

  • [recommended] locking.py top-level import of deployment_ledger.LOCAL_STATE_DIR couples the lock module to the full deployment-state import chain at src/apm_cli/install/locking.py:17
    ~20 command modules import locking at module scope; a single string constant should live in a lightweight module (core/scope.py beside USER_APM_DIR) imported by both ledger and locking.
  • [nit] Relative APM_HOME silently stays relative when _STARTUP_CWD is None at src/apm_cli/core/scope.py:68
    Deleted start dir + relative APM_HOME would float across chdir; fail closed with a clear error.
  • [nit] _receipts_base = apm_home.parent containment base is wider than the prior Path.home() anchor at src/apm_cli/core/deployment_ledger.py:97
    For a shallow APM_HOME like /apm the containment base becomes /; symlink check is the load-bearing guard; document intent.

Test Coverage Expert

  • [recommended] Deployment-root lock symlink rejection has no direct test at tests/unit/install/test_workspace_locking.py:60
    Existing symlink test covers only the metadata lock; the deployment-root lock uses a different base (Path.home()).
    Proof (missing at): tests/unit/install/test_workspace_locking.py -- proves: A symlink at the cross-home serialization lock is rejected before any write. [secure-by-default]

Doc Writer

  • [recommended] CHANGELOG adds a duplicate '### Fixed' heading inside the released [0.31.0] section with an unrelated Specification: preserve GitLab sparse-fetch transport #2938 entry at CHANGELOG.md:287
    Cherry-pick artifact from fix: honor APM_HOME for global user state #2967; violates changelog.instructions.md and is out of scope.
  • [recommended] install.md line 283 still names ~/.apm/ as canonical metadata root; install/update/deps/lock restate the contract instead of linking to it at docs/src/content/docs/reference/cli/install.md:283
    Define once, link elsewhere; Done-when requires install docs to state the contract correctly.
  • [nit] Env-var page says APM reads APM_HOME once at process start, but get_apm_home reads env per call; only startup cwd (and CONFIG_DIR) are captured once at docs/src/content/docs/reference/environment-variables.md
    Docs must match mechanism.

DevX UX Expert

  • [recommended] approve_cmd and deny_cmd Click docstrings still hardcode ~/.apm/config.json in --help at src/apm_cli/commands/approve.py:153
    Click renders docstrings as command help; flag text says 'APM user config' while description says ~/.apm/config.json.
  • [nit] Busy-lock error for ~/.apm-local/ lock gives no context about cross-home serialization at src/apm_cli/install/locking.py:118
    A user with APM_HOME set may be confused that the blocking lock is outside their home.
  • [nit] --global help uses three different abstract nouns across commands
    Minor discoverability gap; install -g carries the full explanation.

Performance Expert

  • [nit] locking.py imports deployment_ledger at top level for a string constant at src/apm_cli/install/locking.py:17
    Pulls ~2k lines of modules at import for '.apm-local'.

Supply Chain Security Expert

  • [nit] Relative APM_HOME silently stays floating when _STARTUP_CWD is unavailable at import at src/apm_cli/core/scope.py:72
    Fail closed instead of returning an unanchored path; practically unreachable.

Auth Expert

  • [nit] Three docstrings in config_loader.py still hardcode ~/.apm paths at src/apm_cli/deps/registry/config_loader.py:3
    Internal doc drift in a credential-adjacent module.

This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.


Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.

The cherry-pick from closed PR #2967 added a second Fixed heading with an unrelated GitLab entry inside the released 0.31.0 section. Released sections are not rewritten and the entry is outside #2884's scope. Addresses doc-writer panel finding on PR #3614.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
install.md still named ~/.apm/ as the canonical metadata root, and install/update/deps/lock each restated the APM_HOME contract. They now link the env-var reference instead; the env-var page no longer claims APM_HOME is read once. approve/deny --help, config_loader docstrings and lock -g help name the APM user home. Addresses doc-writer, devx-ux and auth panel findings on PR #3614.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Adds a symlink-rejection regression for the ~/.apm-local deployment-root lock, loads LOCAL_STATE_DIR lazily so importing locking no longer pulls the deployment ledger, names the shared lock in the busy error, fails closed when a relative APM_HOME cannot be anchored, and documents the receipts containment base. Addresses test-coverage, python-architect, performance, devx-ux and supply-chain panel findings on PR #3614.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The user-scope metadata location (APM_HOME) and lifecycle lock placement are CLI configuration, not OpenAPM manifest, lockfile or resolution behaviour, so no req anchor applies (#2884).

apm-spec-waiver: APM_HOME relocates CLI user-state paths only; no OpenAPM manifest, lockfile or resolution behaviour changes

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
get_apm_home() now errors when a relative APM_HOME cannot be anchored because the start directory is gone; the env-var contract and apm-guide state it. Addresses doc-writer delta panel finding on PR #3614.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

# Conflicts:
#	docs/src/content/docs/reference/cli/view.md
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
#3608 added a longer view summary and #3643 added a check that root summaries are not truncated at 80 columns; together they fail tests/unit/test_cli_consistency.py on main and on every PR merge ref. Shorten the summary so the CI merge ref for this PR is green.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This reverts commit bed006f. Lane F owns the main hotfix for the #3608 x #3643 root-help truncation; this PR stays out of that change.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_now

Delta pass: all five prior follow-ups folded with regression traps; seven panelists return zero findings -- APM_HOME single-root contract is clean.

panel-mode=delta; personas=python-architect,test-coverage-expert,doc-writer,devx-ux-expert,performance-expert,supply-chain-security-expert,auth-expert,apm-ceo

cc Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

The last full-panel advisory (comment 6831053980) returned ship_with_followups and listed five open follow-ups: a symlink-rejection test for the deployment-root lock, a stray CHANGELOG hunk, hardcoded paths in --help docstrings, an install.md restatement of the canonical root, and the top-level deployment_ledger import. Every one of those is now folded. The symlink test, the fail-closed relative-APM_HOME test, and the busy-hint assertion all land with mutation-break verification. The architect's suggestion to hoist LOCAL_STATE_DIR into core/scope.py was resolved by lazy-importing it inside deployment_root_lock() instead, preserving the install-deployment-provenance-state boundary guard that reserves the '.apm-local' literal to the deployment owner; the architect accepted this, and the performance expert confirmed the lazy import removes the startup cost.

Seven delta panelists each returned an empty findings array. The doc-writer's intermediate finding (document the fail-closed relative APM_HOME case) was folded in bd537cd and re-checked clean. No dissent, no new surfaces. Since that pass the branch only merged current main (including hotfix #3651); a re-audit found no new APM user-state root re-derivations.

Aligned with: Secure by default: relative APM_HOME without a start directory fails closed, and both lifecycle locks reject symlinks. Governed by policy: APM_HOME is the single documented root, enforced by the registry_delegation.apm_home_resolution guard. Pragmatic as npm: lazy import keeps startup flat; the busy-lock hint says what is contending and why.

Panel summary

Persona B R N Takeaway
Python Architect 0 0 0 All three prior findings resolved cleanly; no new architectural issues.
Test Coverage Expert 0 0 0 Deployment-root lock symlink gap closed; every behavioral fold carries a regression trap.
Doc Writer 0 0 0 Prior findings fixed; contract links resolve; fail-closed fold accurate.
DevX UX Expert 0 0 0 --help paths, lock -g noun and busy-lock hint resolved; error wording actionable.
Performance Expert 0 0 0 Lazy import removes the startup cost; no new hot-path cost.
Supply Chain Security Expert 0 0 0 Fail-closed anchoring and symlink rejection preserve integrity invariants.
Auth Expert 0 0 0 No token or credential resolution touched; docstrings fixed.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Recommendation

All five follow-ups from the prior advisory are folded and verified. Seven panelists converge on zero findings. The PR is CI-green, Copilot-drained, and CLA-passed. Recommend the maintainer land this at convenience to unblock the scope-migration chain (#3006 / PR #3610). No post-merge follow-ups remain.

Folded in this run

Copilot signals reviewed

  • src/apm_cli/install/locking.py:44 -- LEGIT: moving the lock under APM_HOME dropped main's per-OS-user serialization (resolved in ac53bb7).
  • src/apm_cli/core/scope.py:54 -- LEGIT: relative APM_HOME re-resolved after chdir nested to metadata/metadata (resolved in 359d6c8).

Regression-trap evidence (mutation-break gate)

  • tests/unit/install/test_workspace_locking.py::test_different_apm_homes_still_serialize_on_the_deployment_root -- deleted the deployment-root lock acquisition; test FAILED as expected; guard restored.
  • tests/unit/install/test_workspace_locking.py::test_deployment_root_lock_rejects_symlink_without_touching_target -- deleted the symlink rejection on the deployment-root lock; test FAILED as expected; guard restored.
  • tests/unit/core/test_scope.py::TestGetApmDir::test_relative_apm_home_is_anchored_to_startup_cwd and tests/unit/commands/test_lock_command.py::test_global_lock_keeps_relative_apm_home_anchored_after_chdir -- deleted the start-directory anchoring; tests FAILED as expected; guard restored.
  • tests/unit/core/test_scope.py::TestGetApmDir::test_relative_apm_home_fails_closed_without_startup_cwd -- deleted the fail-closed check; test FAILED as expected; guard restored.

Lint contract

ruff check and ruff format --check (pinned 0.15.12, including scripts/architecture_linter) silent; pylint R0801 10.00/10; lint-auth-signals.sh and lint-architecture-boundaries.sh clean.

CI

All 23 checks pass at 56160d7 (Lint, Build & Test shards, Lifecycle Smoke shards, Windows gates, Spec conformance, Architecture ratchets, CodeQL analyze, license/cla); 3 skipped by design (after 1 CI fix iteration: Mode B waiver).

Mergeability status

PR head SHA CEO stance iters folds defers Copilot rounds CI mergeable mergeStateStatus notes
#3614 56160d7 ship_now 2 13 0 2 green MERGEABLE BLOCKED pending required review

Convergence

2 outer iteration(s); 2 Copilot round(s). Final panel stance: ship_now. Closes #2884 (full record scope). Ready for maintainer review.


Generated by autopilot-pr-merge-worker. This comment is AI-generated and may contain errors.

Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 12, 2026
…t-marketplaces

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit a993ce3 into main Nov 12, 2026
26 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-apm-home-user-root-2884 branch November 12, 2026 22:11
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 12, 2026
…anifest-marketplaces

Resolve the #3367 conflict in marketplace add by threading --offline and local apm.yml authoring catalogs through the canonical registration owner (probe_registration offline=, local_source_points_to_file, local hint on MarketplaceManifestNotFoundError) instead of a second inline probe in the command.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 12, 2026
Resolve tests/conftest.py: keep both hermetic env pops (CODEX_HOME from
this PR, APM_HOME from #3614).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 13, 2026
…3707)

* fix(tests): use an OS-absolute APM_HOME in scripts log path test

On Windows '/custom/apm' is drive-relative, so get_apm_home() (since #3614)
correctly anchors it to the startup drive (D:\custom\apm). The test compared
against the un-anchored string and failed on the Windows release lane. Use a
tmp_path-based APM_HOME, compare Path objects, and mark the test windows_compat
so the PR-time Windows gate covers it.

Refs #2884

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(changelog): fold #3707 into the APM_HOME entry

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 13, 2026
…led by apm install -g (#3610)

* fix: honor APM_HOME for global user state

Centralize APM-owned user metadata under APM_HOME while keeping target deployment paths independent. Document and test the contract across package, config, lifecycle, and architecture boundaries.

* feat(marketplace): declare marketplaces in the user manifest, reconciled by apm install -g

Add a 'marketplaces:' list (name + an existing 'apm marketplace add'
source form, optional ref) to the user manifest at the effective APM
user root. 'apm install -g' reconciles it before resolving
dependencies: registers missing entries, updates changed ones and
removes only manifest-origin entries. The registry records each
entry's origin; manual registrations are never overwritten or
removed, and name conflicts are reported. Project and package
manifests that declare 'marketplaces:' fail with an error naming the
user manifest.

The source-to-registration step is extracted from 'marketplace add'
into marketplace.registration so both paths share one parser/probe.

Refs #3006

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(changelog): reference #3610

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix: complete APM_HOME contract for receipts, marketplaces and docs (#2884)

Finish the APM_HOME single-root contract on top of the cherry-picked
change from @WilliamK112 (closed PR #2967):

- Deployment receipts move under get_apm_home(); the deploy-root
  .apm-local identity stays with the deployment root, like target files.
- The architecture guard also pins the deployment ledger consumer.
- Tests: subprocess isolation (two APM_HOME values, every global
  command family) and parity (unset/empty == ~/.apm); conftest drops a
  developer APM_HOME so the suite stays hermetic.
- Docs: env-var contract lists marketplace registrations, receipts,
  lock, precedence, migration and the out-of-contract paths; apm-guide
  and CHANGELOG updated (entry moved to Unreleased).

Co-authored-by: Ching-Wei Kang <164879897+WilliamK112@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* test: run APM_HOME isolation through the apm binary fixture (#2884)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(changelog): reference #3614 for APM_HOME entry

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* test(marketplace): user-manifest marketplaces follow APM_HOME (#2884)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(scope): anchor a relative APM_HOME to the start directory

apm lock -g and apm update -g chdir into the APM home, so a relative APM_HOME such as 'metadata' resolved to metadata/metadata on later lookups and split the manifest from its lockfile, modules and config. get_apm_home() now expands a leading ~ and anchors a relative value once against the working directory captured at import. Addresses Copilot inline on src/apm_cli/core/scope.py:54 (#2884).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(locking): serialize state changes across APM_HOME values

Moving the lifecycle lock under APM_HOME let processes with different homes mutate the same project or harness directories at once, so a failed install's rollback could overwrite another operation's manifest. acquire_lifecycle_lock() now takes the OS-user deployment-root lock in ~/.apm-local/ (named by the deployment owner) before the APM_HOME metadata lock and releases both together; unset APM_HOME keeps the ~/.apm layout. Adds a cross-home contention regression and updates home write-set snapshots and the pre-compile lock probe. Addresses Copilot inline on src/apm_cli/install/locking.py:44 (#2884).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(apm-home): document relative values and cross-home locking

The APM_HOME path contract now states that ~ is expanded, a relative value resolves against the start directory, and ~/.apm-local/.apm-lifecycle.lock serializes commands across APM_HOME values. Mirrors the change in apm-guide and the CHANGELOG entry (#2884).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(changelog): drop stray #2938 entry from the 0.31.0 block

The cherry-pick from closed PR #2967 added a second Fixed heading with an unrelated GitLab entry inside the released 0.31.0 section. Released sections are not rewritten and the entry is outside #2884's scope. Addresses doc-writer panel finding on PR #3614.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(apm-home): link the path contract and fix stale ~/.apm wording

install.md still named ~/.apm/ as the canonical metadata root, and install/update/deps/lock each restated the APM_HOME contract. They now link the env-var reference instead; the env-var page no longer claims APM_HOME is read once. approve/deny --help, config_loader docstrings and lock -g help name the APM user home. Addresses doc-writer, devx-ux and auth panel findings on PR #3614.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(locking): harden the cross-home lock and relative APM_HOME

Adds a symlink-rejection regression for the ~/.apm-local deployment-root lock, loads LOCAL_STATE_DIR lazily so importing locking no longer pulls the deployment ledger, names the shared lock in the busy error, fails closed when a relative APM_HOME cannot be anchored, and documents the receipts containment base. Addresses test-coverage, python-architect, performance, devx-ux and supply-chain panel findings on PR #3614.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* chore(spec): record Mode B waiver for the APM_HOME user-state root

The user-scope metadata location (APM_HOME) and lifecycle lock placement are CLI configuration, not OpenAPM manifest, lockfile or resolution behaviour, so no req anchor applies (#2884).

apm-spec-waiver: APM_HOME relocates CLI user-state paths only; no OpenAPM manifest, lockfile or resolution behaviour changes

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(apm-home): document the fail-closed relative APM_HOME case

get_apm_home() now errors when a relative APM_HOME cannot be anchored because the start directory is gone; the env-var contract and apm-guide state it. Addresses doc-writer delta panel finding on PR #3614.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(view): fit the root help summary in 80 columns

#3608 added a longer view summary and #3643 added a check that root summaries are not truncated at 80 columns; together they fail tests/unit/test_cli_consistency.py on main and on every PR merge ref. Shorten the summary so the CI merge ref for this PR is green.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Revert "fix(view): fit the root help summary in 80 columns"

This reverts commit bed006f. Lane F owns the main hotfix for the #3608 x #3643 root-help truncation; this PR stays out of that change.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(marketplace): reconcile never destroys entries it cannot replace

A malformed user manifest root (empty, list, scalar or invalid YAML)
read as "no marketplaces" and removed every manifest-owned
registration before package parsing rejected the file. A failed fetch
for a renamed or moved entry still removed the stale one. Dry runs and
no-op runs created marketplaces.json and config.json.

Reject a non-mapping root before the registry is read, skip removals
while any declared entry failed, and read the registry without
creating files (read_registered_marketplaces).

Addresses Copilot inline on src/apm_cli/marketplace/reconcile.py:116,
:117 and :140.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* refactor(marketplace): add parses SOURCE through the shared owner

`apm marketplace add` still split #ref fragments, resolved ref
precedence and classified direct URLs itself, a second authority for
the grammar the user-manifest reconcile parses with
parse_registration_source. Normalize the CLI-only --branch alias at
the command boundary and route add through the shared parser.

Extend the marketplace-source-admission owner to registration.py and
its guard: add and reconcile must call parse_registration_source, and
the command may not re-split fragments or classify direct URLs.
Behavioural, architecture and mutation tests cover the boundary, plus
regressions for the three reconcile safety fixes.

Addresses Copilot inline on src/apm_cli/marketplace/registration.py:89.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(install): keep commands/install.py within the 2100-line guard

main already sits at the 2100-line cap, so the reconcile hook pushed
install.py to 2105 and failed the Lint file-length guardrail. Make the
hook a single call (the user-scope check moves into
reconcile_user_marketplaces_or_exit) and collapse a single-name import.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* docs(marketplace): follow APM_HOME and state reconcile limits

The user manifest path now reads $APM_HOME/apm.yml (default
~/.apm/apm.yml) everywhere this PR documents it, the source column
notes that entries have no --host equivalent, failure and hand-over
wording matches the code, apm install's reference notes the reconcile
step, the CHANGELOG leads with the benefit, the apm-guide row is
shorter and the "Declare instead of add" callout opens the add
section.

Addresses panel follow-ups from doc-writer, devx-ux-expert and
oss-growth-hacker.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* refactor(marketplace): one registry write per reconcile, clearer output

Fetch every new or changed entry first, then apply all registrations
and removals in one locked transaction (apply_manifest_marketplaces)
instead of a lock-read-write cycle per entry. Removals use the [-]
symbol, the kept line pluralizes, a single failure is named directly,
and the manual-conflict warning shows the current source. The source
admission guard now also forbids reconcile.py from re-parsing SOURCE.
The integration module declares its component marker and covers
`apm install -g --dry-run` creating no registry files.

Addresses panel follow-ups from performance-expert, cli-logging-expert,
devx-ux-expert, test-coverage-expert, supply-chain-security-expert and
python-architect.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* fix(marketplace): reject relative local sources in the user manifest

A relative local source such as ./catalog resolved against the
directory where `apm install -g` ran, so the same user manifest
registered different paths (or failed) depending on the cwd. Reject
it with an actionable error; absolute and ~/ paths are unchanged. The
shared not-found hint now says "use the path to the apm.yml file" so it
reads right for both `marketplace add` and a manifest `source:`.

Addresses delta panel follow-ups from doc-writer and cli-logging-expert.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Ching-Wei Kang <164879897+WilliamK112@users.noreply.github.com>
Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
* fix(tests): restore release-gate lanes for 0.36.0

Main's tag-gate lanes (build-release push + manual-build-release) were red
on runs 43381609442, 43381682871 and 43394173235. PR CI never runs them.

Product regressions (Windows/real installs), fixed:
- Hook cleanup removed nothing on Windows: remove_stale_deployed_files
  looked up recorded hashes with POSIX keys while callers passed native
  backslash keys, so content proof failed closed (#3672, Refs #3649).
- describe_path_obstruction returned None on Windows, which reports a
  directory-for-file as EACCES and a file-for-parent as ENOENT instead of
  EISDIR/ENOTDIR (#3709, Refs #3678).
- Skill preflight refused claimed members of an unclaimed, populated skill
  directory that materialization leaves alone, failing a local bundle
  install (Refs #3625).

Stale tests (behaviour changed intentionally), updated:
- policy chain mocks now return real PolicyFetchResult (#2933, Refs #2753)
- bare-cache/downloader/anonymous-https fixtures use real Git checkouts
  (#3603, Refs #3457)
- mcp install help, registry error wording, deps why -g help
  (#3633 Refs #3588, #2803 Refs #2478, #3614 Refs #2884)
- downloader stub carries carried_licenses (#3646, Refs #3556)
- frozen-hash lifecycle uses a generic git host so -g URL validation
  uses git ls-remote instead of a live api.github.com 404 (#3672)

New Windows-shaped regression tests are marked windows_compat.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* chore: spec waiver for release-gate repair

apm-spec-waiver: restores pre-existing behaviour on Windows and in skill preflight; no OpenAPM-observable change

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] Document and align APM_HOME behavior for global user state

3 participants