GeezerVison

add(marketplace): load live local catalogs directly from apm.yml

TL;DR

Allow apm marketplace add ./apm.yml --name alice-dev to register an explicitly selected local authoring catalog without generating JSON first.
Later explicit operations reread that file, while each invocation uses one configuration snapshot.
Selected installs retain the actual package dependency and existing lockfile semantics.

Issue and approved scope

Fixes #2729.

Human approval: #2729 (comment)

Review contact: Daniel Meppiel (@danielmeppiel).

This implements the bounded local-authoring change.
Registry-backed authoring, durable catalog-following intent, and the separate enterprise API conformance scenario remain with their respective issues.

Problem (WHY)

• Authoring already lives in YAML, but registration previously attempted to decode the file as JSON. The canonical issue states that "Marketplace metadata and package entries can be declared in apm.yml".
• Requiring an intermediate generated catalog adds a separate step and stale-output risk: the issue describes generated output becoming "stale relative to apm.yml".
• The change is backed by executable scenarios rather than the example command alone, following "Instruct the agent to validate its own work before moving on.".

Approach (WHAT)

• Recognize only an explicitly selected local apm.yml; retain existing source classification for JSON, Git and hosted JSON.
• Reuse canonical authoring validation, ref resolution, catalog mapping and path containment.
• Cache the successful in-memory catalog only in the current Click invocation.
• Expose bounded --offline behavior on marketplace add and marketplace browse.

Implementation (HOW)

The dashed nodes identify the new local input and its in-memory discovery view; existing consumer and lockfile owners remain downstream.

flowchart LR
    A[Explicit local apm.yml] --> B[Canonical authoring parser]
    B --> C[Canonical ref resolver]
    C --> D[In-memory discovery composer]
    D --> E[Existing marketplace consumer]
    E --> F[Browse or view]
    E --> G[Install selected actual dependency]
    G --> H[Existing manifest and lockfile]
    I[JSON or Git or HTTPS catalog] --> E
    classDef added stroke-dasharray:5 5
    class A,D added

The diagram was rendered successfully with mmdc.

Trade-offs

• Discovery does not fetch cosmetic manifests for every remote package. Explicit curator fields and existing local metadata remain available; remote ref resolution is still explicit and can require network access.
• --offline is limited to this local YAML path. Full commit SHAs and local entries work without network; tags and ranges are not persisted for later offline invocations.
• Native pluginRoot layout hints are omitted from the temporary discovery view so authored paths remain relative to the selected file. Native generated catalogs retain their original representation, verified before and after discovery composition.
• Snapshots are invocation-local, with no watcher or persistent generated preview. A later explicit operation validates the current file again and reports edits or deletion.

Benefits

1. Register and browse a valid local authoring file without running apm pack.
2. Install one selected package without installing an unselected package's inventory or executable hooks.
3. Replay a remote dependency from its lock in a fresh configuration scope after removing the author's preview directory.

Validation

Python 3.12.15 and dependencies installed from the unchanged uv.lock with uv sync --frozen --extra dev --extra build.

Marketplace regression suite and new architecture guard:

1785 passed, 5 deselected in 90.29s (0:01:30)

The five deselections are symlink-related cases requiring privileges unavailable to this Windows account. They are not disabled in the committed suite.

PyInstaller 6.17.0 packaged executable, selected through APM_BINARY_PATH:

8 passed in 38.87s

Full Ruff lint and formatting:

All checks passed!
2095 files already formatted

Full duplication check (pylint R0801):

Your code has been rated at 10.00/10

Architecture linter exited 0. Auth and assertion/duplicate ratchets:

[+] auth-signal lint clean
[+] assertion-quality ratchet clean: AQ001=4, AQ002=12
[+] exact test duplicate ratchet clean: 1418 files, 0 allowed duplicate group(s)

Documentation build and generated-page link checks:

20:55:52 [build] 126 page(s) built in 43.50s
[+] Checked 1113 relative link(s) across generated pages. No broken relative links found.

git diff --check passed. These are local Windows results; required GitHub checks and maintainer review still apply.

Scenario Evidence

How to test

• Install the locked development environment: uv sync --frozen --extra dev --extra build.
• Run uv run --frozen pytest tests/unit/marketplace tests/integration/test_architecture_authoring_source.py; expect the marketplace suite to pass on the CI platform.
• Run uv run --frozen pytest tests/integration/test_marketplace_authoring_lifecycle.py; expect all eight scenarios to pass using the installed CLI. For packaged validation, build with build/apm.spec, set APM_BINARY_PATH to the resulting executable, and repeat.
• Register a valid local catalog with apm marketplace add ./apm.yml --name alice-dev, edit it, and browse again. Expect current entries with no generated catalog writes; a malformed edit must fail without replacing registration.
• Run the repository Ruff, pylint duplication, auth/architecture and test-quality guards, then cd docs && npm ci && npm run build; expect clean checks and valid relative links.

Type of change and testing

• New feature
• Documentation
• Tested locally, including the packaged executable
• Added behavioral and architecture regression tests
• Required GitHub checks and maintainer review completed

Spec conformance

• N/A: no normative requirement, public schema or lockfile format changes. This adds a local authoring input to existing registration and package-source contracts.