fix: address Copilot review feedback — docs accuracy, path security, crash guard

- Fix docs claiming #ref overrides unversioned plugins (it does not)
- Fix docs claiming git tag fallback for plugins without versions
- Remove -p alias from docs (not in CLI implementation)
- Add resolved_version to lockfile-spec documentation
- Add --plugin flag to skill file command reference
- Remove unused PluginNotFoundError import in view.py
- Guard caret pin hint against non-semver version entries
- Wrap _expand_specifier in try/except for raw git ref version_specs
- Add path traversal protection via ensure_path_within for source.path

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

Author: Sergio Sisternes

docs/src/content/docs/guides/marketplaces.md

@@ -162,9 +162,9 @@ apm install code-review@acme-plugins#~2.1.0
 apm install code-review@acme-plugins#>=1.0.0,<3.0.0
 ```
 
-The `#` separator carries a version specifier when the plugin declares `versions`, or a raw git ref when it does not. Plugins without `versions` continue to work as before.
+The `#` separator carries a version specifier only when the plugin declares `versions`. For plugins without `versions`, APM uses the source defined in the marketplace manifest, including any `source.ref` value; `#<ref>` does not override unversioned entries.
 
-APM resolves the plugin name against the marketplace index, fetches the underlying Git repository at the resolved ref, and installs it as a standard APM dependency. The resolved source appears in `apm.yml` and `apm.lock.yaml` just like any direct dependency.
+APM resolves the plugin name against the marketplace index, fetches the underlying Git repository using the ref defined by the selected marketplace entry, and installs it as a standard APM dependency. The resolved source appears in `apm.yml` and `apm.lock.yaml` just like any direct dependency.
 
 For full `apm install` options, see [CLI Commands](../../reference/cli-commands/).
 
@@ -176,7 +176,7 @@ Show available versions for a marketplace plugin:
 apm view code-review@acme-plugins
 ```
 
-Displays a table of versions with their refs, sorted newest-first. For plugins without `versions`, shows remote tags and branches.
+Displays a table of versions with their refs, sorted newest-first. Plugins without `versions` show a "no version history" message.
 
 ## Provenance tracking
 

docs/src/content/docs/reference/cli-commands.md

@@ -644,7 +644,7 @@ apm view microsoft/apm-sample-package -g
 - Shows package name, version, description, source, install path, context files, workflows, and hooks
 - `versions` lists remote tags and branches without cloning the repository
 - `versions` does not require the package to be installed locally
-- `NAME@MARKETPLACE` syntax shows the plugin's declared `versions` array sorted newest-first; for plugins without `versions`, falls back to remote tags and branches
+- `NAME@MARKETPLACE` syntax shows the plugin's declared `versions` array sorted newest-first; plugins without `versions` show no version history
 
 ### `apm outdated` - Check locked dependencies for updates
 
@@ -1070,7 +1070,7 @@ apm marketplace publish [OPTIONS]
 
 **Options:**
 - `-m, --marketplace TEXT` - Target marketplace name
-- `-p, --plugin TEXT` - Plugin name in the marketplace (default: `name` from `apm.yml`)
+- `--plugin TEXT` - Plugin name in the marketplace (default: `name` from `apm.yml`)
 - `--version TEXT` - Version to publish as semver `X.Y.Z` (default: `version` from `apm.yml`)
 - `--ref TEXT` - Git ref or commit SHA (default: current HEAD)
 - `--force` - Overwrite existing version entry with a different ref

docs/src/content/docs/reference/lockfile-spec.md

@@ -126,6 +126,7 @@ fields:
 | `deployed_files` | array of strings | MUST | Every file path APM deployed for this dependency, relative to project root. |
 | `source` | string | MAY | Dependency source. `"local"` for local path dependencies. Omitted for remote (git) dependencies. |
 | `version_spec` | string | MAY | Original semver range from the install specifier (e.g., `"^2.0.0"`). Present only for marketplace dependencies installed with a version constraint. Used by `apm outdated` to evaluate updates within the pinned range. |
+| `resolved_version` | string | MAY | Concrete version selected after marketplace semver resolution (e.g., `"2.3.1"`). Present only when APM resolved a marketplace dependency from a version constraint. Omitted for raw git refs and unversioned plugins. |
 | `local_path` | string | MAY | Filesystem path (relative or absolute) to the local package. Present only when `source` is `"local"`. |
 
 Fields with empty or default values (empty strings, `false` booleans, empty

packages/apm-guide/.apm/skills/apm-usage/commands.md

@@ -57,7 +57,7 @@
 | `apm marketplace browse NAME` | Browse marketplace packages | -- |
 | `apm marketplace update [NAME]` | Update marketplace index | -- |
 | `apm marketplace remove NAME` | Remove a marketplace | `-y` skip confirm |
-| `apm marketplace publish` | Publish version to marketplace.json | `-m MARKETPLACE`, `--version`, `--ref`, `--force`, `--dry-run` |
+| `apm marketplace publish` | Publish version to marketplace.json | `-m MARKETPLACE`, `--plugin`, `--version`, `--ref`, `--force`, `--dry-run` |
 | `apm marketplace validate NAME` | Validate marketplace manifest | `--check-refs`, `-v` |
 | `apm search QUERY@MARKETPLACE` | Search marketplace | `--limit N` |
 | `apm install NAME@MKT#^X.Y.Z` | Install with semver range | Supports `^`, `~`, `>=`, exact |

src/apm_cli/commands/marketplace.py

@@ -895,6 +895,10 @@ def publish(marketplace_name, version_str, ref, plugin_name, dry_run, force, ver
 
         marketplace_file = os.path.join(local_repo, source.path)
 
+        # Validate path to prevent traversal attacks via malicious source.path
+        from ..utils.path_security import ensure_path_within
+        ensure_path_within(Path(marketplace_file), Path(local_repo))
+
         if not os.path.isfile(marketplace_file):
             logger.error(
                 f"marketplace.json not found at expected path: "

src/apm_cli/commands/outdated.py

@@ -143,7 +143,10 @@ def _check_marketplace_versions(dep, verbose):
         # Check version_spec if available (field added by parallel task)
         version_spec = getattr(dep, "version_spec", None)
         if version_spec:
-            constraints = _expand_specifier(version_spec)
+            try:
+                constraints = _expand_specifier(version_spec)
+            except ValueError:
+                constraints = None
             if constraints and not _version_matches(best_parsed, constraints):
                 # Find best version within the range
                 best_in_range = None

src/apm_cli/commands/view.py

@@ -253,7 +253,7 @@ def _display_marketplace_versions(
     Fetches the marketplace manifest, finds the plugin, and renders its
     ``versions[]`` array as a Rich table (with plain-text fallback).
     """
-    from ..marketplace.errors import MarketplaceFetchError, PluginNotFoundError
+    from ..marketplace.errors import MarketplaceFetchError
     from ..marketplace.models import MarketplaceSource
     from ..marketplace.registry import get_marketplace_by_name
     from ..marketplace.client import fetch_or_cache
@@ -334,10 +334,11 @@ def _display_marketplace_versions(
         console.print(table)
         click.echo("")
         click.echo(f"  Install: apm install {plugin_name}@{marketplace_name}")
-        click.echo(
-            f"  Pin:     apm install {plugin_name}@{marketplace_name}"
-            f"#^{sorted_versions[0].version}"
-        )
+        if latest_version:
+            click.echo(
+                f"  Pin:     apm install {plugin_name}@{marketplace_name}"
+                f"#^{latest_version}"
+            )
 
     except ImportError:
         # Plain-text fallback