feat: improve version pinning guidance and CLI visibility

[danielmeppiel]

Summary

Improves version pinning guidance across CLI and documentation per community feedback. Also removes the confusing @alias shorthand syntax.

Closes #336

Changes

CLI — resolved ref visibility

• Install output now shows resolved ref: ✓ microsoft/apm-sample-package @ main (a1b2c3d4) instead of just ✓ microsoft/apm-sample-package
• Cached deps also show resolved SHA from lockfile for consistency
• One-time info hint when any dependency has no explicit ref: Tip: Pin versions with #tag or #sha for reproducible installs
• Blue info color, not yellow warning — this is guidance, not a problem

Documentation — pinned examples

Updated all prominent examples to show #v1.0.0 pinned form:

• README.md — install command and apm.yml example
• quick-start.md — install command and dependency listing
• dependencies.md — Quick Start and Real-World Example sections
• manifest-schema.md — clarified comments, pinned appendix example
• templates/hello-world/apm.yml — default template

apm-sample-package

• Tagged microsoft/apm-sample-package with v1.0.0 so docs reference a real version

Removed: @alias shorthand syntax

The @ separator in shorthand strings (e.g. owner/repo@my-alias) conflicted with conventions in npm (@scope), Go (@version), and Cargo (@version), causing real confusion — our own docs had a bug where @standards was intended as a branch ref.

The shorthand @alias had zero real-world usage (0 YAML fixtures, 0 production examples, 0 guide mentions). Changes:

• Removed @ alias parsing from DependencyReference.parse() shorthand form
• Removed ["@" alias] from ABNF grammar
• Dict format alias: field is preserved — it's unambiguous and still documented in object-format sections

Design principles (per issue #336)

• ❌ Don't mandate version pins (npm/pip/uv don't)
• ❌ Don't block unversioned installs
• ✅ Guide through examples and visibility, not enforcement
• ✅ Show what was resolved (like npm shows resolved versions)

Tests

All 2440 unit tests passing.

[Copilot]

Pull request overview

Improves version pinning guidance and visibility by updating docs/templates to use pinned dependency examples and enhancing CLI install output to display resolved refs plus a helpful tip when unpinned dependencies are present.

Changes:

• Update docs and the hello-world template to use #v1.0.0 pinned dependency examples.
• Update CLI install output to include the resolved ref next to the package name.
• Add an informational tip at the end of install when any dependency lacks an explicit ref.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
templates/hello-world/apm.yml	Pins the default sample dependency to #v1.0.0 in the template.
src/apm_cli/commands/install.py	Adds resolved-ref display in install output and prints a tip when deps are unpinned.
docs/src/content/docs/reference/manifest-schema.md	Updates schema examples/comments to show pinned refs and “latest” semantics.
docs/src/content/docs/guides/dependencies.md	Pins prominent dependency examples to #v1.0.0.
docs/src/content/docs/getting-started/quick-start.md	Pins install command and manifest examples to #v1.0.0.
README.md	Pins the main install and manifest examples to #v1.0.0.

[Copilot]

Pull request overview

Improves dependency version pinning guidance by updating docs/templates to use pinned examples and enhancing apm install output to show the resolved ref/commit for better reproducibility visibility.

Changes:

• Update apm install output to display the resolved git ref (and short SHA) and emit a one-time tip when any dependency is unpinned.
• Remove shorthand @alias parsing from dependency strings (keeping dict-form alias:), and update tests accordingly.
• Update docs/templates/README examples to use #v1.0.0 pinned dependencies and adjust reference docs for the updated grammar.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/apm_cli/commands/install.py	Shows resolved ref in install output and adds a one-time pinning tip.
src/apm_cli/models/dependency.py	Removes @alias from string canonicalization/stringification and tightens dict alias validation.
tests/unit/test_package_identity.py	Updates parsing expectations to reflect removal of shorthand @alias.
tests/unit/test_generic_git_urls.py	Updates URL parsing tests to reject shorthand @alias.
tests/unit/test_canonicalization.py	Updates canonicalization/identity tests for new alias behavior.
tests/test_apm_package_models.py	Updates model parsing/string tests to reflect alias shorthand removal and dict alias support.
tests/test_enhanced_discovery.py	Updates expected dependency order now that shorthand alias isn’t used.
docs/src/content/docs/getting-started/quick-start.md	Pins the sample dependency in install and apm.yml examples.
docs/src/content/docs/guides/dependencies.md	Pins prominent examples and updates object-form description (but currently drops alias mention).
docs/src/content/docs/reference/manifest-schema.md	Removes @alias from shorthand grammar and pins examples.
docs/src/content/docs/reference/primitive-types.md	Removes alias-based example and updates resulting directory layout illustration.
templates/hello-world/apm.yml	Pins microsoft/apm-sample-package to #v1.0.0.
README.md	Pins sample dependency usage in the quick examples.
CHANGELOG.md	Adds Unreleased entries for install output/tip and notes shorthand alias removal.

Comments suppressed due to low confidence (1)

docs/src/content/docs/guides/dependencies.md:141

• This line claims the object format is only for git, path, and ref, but the schema/code still accept an optional alias field for object dependencies. Update the field list to include alias (and a short constraint) or remove alias support from the implementation for consistency.

Fields: `git` (required), `path`, `ref` (all optional). The `git` value is any HTTPS or SSH clone URL.