feat(marketplace): inherit description/version from local-path apm.yml

Local-path packages (`source: ./...`) now use the same fallback as
remote sources when the curator entry under `marketplace.packages`
omits `description` or `version`: `apm pack` reads the field from
the package's own `apm.yml` and writes it to `marketplace.json`. A
curator-side value still wins when set. Path resolution is constrained
to the project root, and a source that resolves to the marketplace's
own `apm.yml` is skipped.

Follow-up to #1061, which added the same behavior for remote sources.

Author: imbabamba

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- `apm pack` now reads `description` and `version` from a local-path package's own `apm.yml` and falls back to those values in the generated `marketplace.json` when the curator entry under `marketplace.packages` omits them. Mirrors the fallback that already runs for remote sources; a curator-side value still wins when set. The local read is constrained to the project root and skips a source that resolves to the marketplace's own `apm.yml`.
 - `apm install -g --target copilot` now deploys prompt primitives to `~/.copilot/prompts/` while continuing to filter unsupported user-scope instructions. (closes #1482, #1570)
 - Linux standalone `apm` binaries no longer fail git shared-cache clones with shared-library symbol lookup errors caused by PyInstaller dynamic-library paths leaking into child processes. (closes #1534)
 - Avoid 13-minute `apm install` hangs in large local projects by limiting synthetic `_local` discovery to `.apm/` and `.github/`, while preserving package metadata discovery. (closes #1507) -- by @ioannispoulios

docs/src/content/docs/reference/manifest-schema.md

@@ -685,6 +685,8 @@ Each entry MUST be a mapping. Unknown keys are rejected.
 
 Remote packages MUST declare at least one of `version` or `ref`. Local packages (sources beginning with `./`) skip git resolution and have no version requirement.
 
+When `description` or `version` is omitted from a `packages[]` entry, `apm pack` reads the matching field from the referenced package's own `apm.yml` and uses it in the generated `marketplace.json`. Remote packages are fetched over HTTPS (skipped under `--offline`); local packages are read from disk under the project root. A curator-side value still wins when both are set.
+
 The first three `source` forms target a remote git host; the second and third name a non-default host (e.g. GitHub Enterprise, self-hosted GitLab) as either a shorthand or a full HTTPS URL with an optional `.git` suffix that is normalized away. Path traversal (`..`) in local paths, userinfo (`user@host`), ports, query strings, and non-`https` URL schemes are rejected at parse time.
 
 Non-default hosts authenticate via the standard APM token chain -- see the [authentication guide](../getting-started/authentication/) for the per-host-class lookup order. A token resolved for the default host is never forwarded to a non-default host.

src/apm_cli/marketplace/builder.py

@@ -733,7 +733,62 @@ def resolve(self) -> ResolveResult:
                 ordered.append(results[idx])
         return ResolveResult(entries=tuple(ordered), errors=tuple(errors))
 
-    # -- remote description fetcher -----------------------------------------
+    # -- description/version metadata fetchers ------------------------------
+
+    def _fetch_local_metadata(self, pkg: ResolvedPackage) -> dict[str, str] | None:
+        """Best-effort: read ``description`` and ``version`` from a
+        local-path package's ``apm.yml`` on disk.
+
+        Local-path packages (``source: ./...``) record the curator's
+        ``source`` value on ``ResolvedPackage.subdir``; the package's
+        own ``apm.yml`` lives at ``<project_root>/<subdir>/apm.yml``.
+        Returns a dict with ``description`` and/or ``version`` keys, or
+        ``None`` when the file is missing or unreadable.  Mirrors
+        ``_fetch_remote_metadata``: cosmetic enrichment only, failures
+        are logged at debug level and never propagate.
+
+        The resolved path is constrained to ``self._project_root`` so a
+        curator entry pointing outside the tree is skipped.  A source
+        that resolves to the project root itself is also skipped -- that
+        file is the marketplace's own ``apm.yml``, not a package
+        manifest.
+        """
+        if not pkg.subdir:
+            return None
+        try:
+            package_root = ensure_path_within(self._project_root / pkg.subdir, self._project_root)
+            if package_root == self._project_root.resolve():
+                return None
+            file_path = package_root / "apm.yml"
+            if not file_path.is_file():
+                return None
+            data = yaml.safe_load(file_path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                return None
+            result: dict[str, str] = {}
+            desc = data.get("description")
+            if isinstance(desc, str) and desc:
+                result["description"] = desc
+            ver = data.get("version")
+            if ver is not None:
+                ver_str = str(ver).strip()
+                if ver_str:
+                    result["version"] = ver_str
+            if result:
+                logger.debug(
+                    "Read local metadata for %s from %s: %s",
+                    pkg.name,
+                    file_path,
+                    ", ".join(result.keys()),
+                )
+                return result
+        except Exception:
+            logger.debug(
+                "Could not read local metadata for %s",
+                pkg.name,
+                exc_info=True,
+            )
+        return None
 
     def _fetch_remote_metadata(self, pkg: ResolvedPackage) -> dict[str, str] | None:
         """Best-effort: fetch ``description`` and ``version`` from the
@@ -865,27 +920,39 @@ def _resolve_github_token(self) -> str | None:
         return None
 
     def _prefetch_metadata(self, resolved: list[ResolvedPackage]) -> dict[str, dict[str, str]]:
-        """Concurrently fetch remote metadata for all packages.
+        """Fetch ``description``/``version`` metadata for resolved packages.
 
         Returns a mapping of ``{package_name: {"description": ..., "version": ...}}``
-        for successful fetches.  Skipped entirely when ``--offline`` is set.
-        Local-path packages are skipped (they carry their own metadata).
-
-        A GitHub token is resolved once before spawning worker threads and
-        stored on ``self._github_token`` for the workers to read.
+        for successful fetches.  Both local-path and remote packages are
+        read from each package's own ``apm.yml`` so the output mapper can
+        apply one fallback rule regardless of source kind.
+
+        Local reads always run (filesystem only).  Remote fetches are
+        skipped when ``--offline`` is set.  A GitHub token is resolved
+        once before spawning worker threads and stored on
+        ``self._github_token`` for the workers to read.
         """
+        results: dict[str, dict[str, str]] = {}
+
+        # Local-path packages: read each apm.yml directly from disk.
+        # Cheap and serial -- no network, no thread pool needed.
+        for pkg in resolved:
+            if pkg.source_repo:
+                continue
+            meta = self._fetch_local_metadata(pkg)
+            if meta:
+                results[pkg.name] = meta
+
         if self._options.offline:
-            return {}
+            return results
 
-        # Filter out local-path entries -- they don't have a remote to fetch from.
         remote = [pkg for pkg in resolved if pkg.source_repo]
         if not remote:
-            return {}
+            return results
 
         # Resolve token once -- threads read self._github_token (immutable).
         self._ensure_auth()
 
-        results: dict[str, dict[str, str]] = {}
         workers = min(self._options.concurrency, len(remote))
         with ThreadPoolExecutor(max_workers=workers) as pool:
             future_to_name = {

src/apm_cli/marketplace/output_mappers.py

@@ -89,10 +89,41 @@ def compose(
             plugin["name"] = pkg.name
 
             if is_local:
+                meta = remote_metadata.get(pkg.name, {})
                 if entry.description:
                     plugin["description"] = entry.description
+                    local_desc = meta.get("description", "")
+                    if local_desc and local_desc != entry.description:
+                        override_count += 1
+                        diagnostics.append(
+                            BuildDiagnostic(
+                                level="verbose",
+                                message=(
+                                    f"[i] Package '{pkg.name}': using curator "
+                                    f"description (package: "
+                                    f"'{local_desc[:40]}')"
+                                ),
+                            )
+                        )
+                elif meta.get("description"):
+                    plugin["description"] = meta["description"]
                 if entry.version:
                     plugin["version"] = entry.version
+                    local_ver = meta.get("version", "")
+                    if local_ver and local_ver != entry.version:
+                        override_count += 1
+                        diagnostics.append(
+                            BuildDiagnostic(
+                                level="verbose",
+                                message=(
+                                    f"[i] Package '{pkg.name}': using curator "
+                                    f"version '{entry.version}' "
+                                    f"(package: '{local_ver}')"
+                                ),
+                            )
+                        )
+                elif meta.get("version"):
+                    plugin["version"] = meta["version"]
             else:
                 meta = remote_metadata.get(pkg.name, {})
                 if entry and entry.description:

tests/unit/marketplace/test_builder.py

@@ -1786,6 +1786,113 @@ def test_no_auth_header_when_no_token(self, tmp_path: Path) -> None:
         assert req.get_header("Authorization") is None
 
 
+# ---------------------------------------------------------------------------
+# _fetch_local_metadata tests
+# ---------------------------------------------------------------------------
+
+
+class TestFetchLocalMetadata:
+    """Tests for best-effort local apm.yml metadata reads."""
+
+    def _make_pkg(
+        self,
+        *,
+        name: str = "local-tool",
+        subdir: str | None = "./packages/local-tool",
+    ) -> ResolvedPackage:
+        return ResolvedPackage(
+            name=name,
+            source_repo="",
+            subdir=subdir,
+            ref="",
+            sha="",
+            requested_version=None,
+            tags=(),
+            is_prerelease=False,
+        )
+
+    def _make_builder(self, tmp_path: Path) -> MarketplaceBuilder:
+        yml_path = _write_yml(tmp_path, _BASIC_YML)
+        return MarketplaceBuilder(yml_path)
+
+    def test_reads_description_and_version_from_apm_yml(self, tmp_path: Path) -> None:
+        """File on disk with both fields -> both returned."""
+        pkg_dir = tmp_path / "packages" / "local-tool"
+        pkg_dir.mkdir(parents=True)
+        (pkg_dir / "apm.yml").write_text(
+            "name: local-tool\ndescription: A local tool\nversion: 1.2.3\n",
+            encoding="utf-8",
+        )
+        builder = self._make_builder(tmp_path)
+        result = builder._fetch_local_metadata(self._make_pkg())
+        assert result is not None
+        assert result["description"] == "A local tool"
+        assert result["version"] == "1.2.3"
+
+    def test_description_only(self, tmp_path: Path) -> None:
+        """File with description but no version -> only description returned."""
+        pkg_dir = tmp_path / "packages" / "local-tool"
+        pkg_dir.mkdir(parents=True)
+        (pkg_dir / "apm.yml").write_text(
+            "name: local-tool\ndescription: Only desc\n",
+            encoding="utf-8",
+        )
+        builder = self._make_builder(tmp_path)
+        result = builder._fetch_local_metadata(self._make_pkg())
+        assert result is not None
+        assert result["description"] == "Only desc"
+        assert "version" not in result
+
+    def test_missing_apm_yml_returns_none(self, tmp_path: Path) -> None:
+        """Subdir exists but has no apm.yml -> None, no crash."""
+        (tmp_path / "packages" / "local-tool").mkdir(parents=True)
+        builder = self._make_builder(tmp_path)
+        result = builder._fetch_local_metadata(self._make_pkg())
+        assert result is None
+
+    def test_missing_subdir_returns_none(self, tmp_path: Path) -> None:
+        """Subdir does not exist -> None, no crash."""
+        builder = self._make_builder(tmp_path)
+        result = builder._fetch_local_metadata(self._make_pkg())
+        assert result is None
+
+    def test_path_escapes_project_root_returns_none(self, tmp_path: Path) -> None:
+        """A subdir that resolves outside the project root is skipped."""
+        builder = self._make_builder(tmp_path)
+        pkg = self._make_pkg(subdir="../escape")
+        result = builder._fetch_local_metadata(pkg)
+        assert result is None
+
+    def test_subdir_resolves_to_project_root_returns_none(self, tmp_path: Path) -> None:
+        """Source that resolves to project root reads the marketplace's own
+        apm.yml, not a package manifest -- skip rather than emit the
+        marketplace description as a package description.
+        """
+        builder = self._make_builder(tmp_path)
+        pkg = self._make_pkg(subdir="./")
+        result = builder._fetch_local_metadata(pkg)
+        assert result is None
+
+    def test_malformed_yaml_returns_none(self, tmp_path: Path) -> None:
+        """Bad YAML -> None, no exception propagates."""
+        pkg_dir = tmp_path / "packages" / "local-tool"
+        pkg_dir.mkdir(parents=True)
+        (pkg_dir / "apm.yml").write_text(
+            "name: local-tool\ndescription: [unclosed",
+            encoding="utf-8",
+        )
+        builder = self._make_builder(tmp_path)
+        result = builder._fetch_local_metadata(self._make_pkg())
+        assert result is None
+
+    def test_empty_subdir_field_returns_none(self, tmp_path: Path) -> None:
+        """Defensive: a ResolvedPackage with subdir=None is skipped."""
+        builder = self._make_builder(tmp_path)
+        pkg = self._make_pkg(subdir=None)
+        result = builder._fetch_local_metadata(pkg)
+        assert result is None
+
+
 class _FakeHTTPResponse:
     """Minimal file-like mock for urllib.request.urlopen return value."""