feat(pack): --create-tag and --push flags to create and push release tag after --check-versions

[danielmeppiel]

Summary

Add --create-tag and --push flags to apm pack. When
--check-versions succeeds, --create-tag creates the git tag the
check is verifying (e.g. v1.2.0 for lockstep marketplaces, or one
per package for per_package). --push follows up by pushing the
created tag to the configured remote. Refuses to operate on a dirty
working tree, on existing tags, or when the manifest version and the
tag-to-create disagree.

Motivation

The current release dance for a marketplace looks like this:

1. Bump marketplace.yml version.
2. apm pack --check-versions --check-clean (release gates).
3. Inspect output.
4. git tag v1.2.0.
5. git push origin v1.2.0.
6. Wait for the marketplace consumers to pick up the new tag.

Steps 4 and 5 are mechanical and error-prone: tag-name typos, forgotten
push, or pushing the wrong commit (e.g. when the local HEAD has
unrelated drift from origin/main). The proposal folds the mechanical
steps into the gated command itself, so the release is one invocation
instead of three, and any failure unwinds cleanly.

Proposal

Two new flags on apm pack:

• --create-tag — after --check-versions succeeds, create the git
  tag(s) implied by the marketplace's versioning strategy:

  • lockstep: one tag v{marketplace_version}.
  • tag_pattern: one tag per package using the configured pattern.
  • per_package: one tag per package using {name}--v{version}
    (Claude Code / PR feat(deps): support marketplace dependencies in plugin.json #1422 convention).

  Tag creation is annotated (git tag -a -m "Release v1.2.0") and
  signed if tag.gpgSign is set in git config.

• --push — after creating tags, push them to the remote inferred
  from git config branch.<current>.remote (default origin). Only
  pushes the newly created tags; never pushes branches.

Both flags require --check-versions to also be set (the version
agreement check is the gate that justifies tag creation).
--push may be used with or without --create-tag, but without
--create-tag it errors out (no tag was made; nothing to push).

Refusal conditions (all exit code 1, distinct messages):

1. Working tree is dirty.
2. Tag(s) already exist locally or on the remote.
3. Manifest's marketplace version disagrees with the tag-to-create.
4. No git remote configured.
5. --check-versions not passed.

Examples

One-shot release:

apm pack --check-versions --check-clean --create-tag --push

Inspection (dry-run; reports tags that would be created and pushed,
makes no git calls):

apm pack --check-versions --create-tag --push --dry-run

Tag locally, push manually later:

apm pack --check-versions --create-tag
git push origin --tags

Considerations

• Composes with --check-clean: when both gates run and both pass,
  tag creation runs.
• Composes with --dry-run: dry-run never invokes git.
• Composes with --json: success/failure of tag creation and push
  are added to the existing JSON output envelope under
  tag_creation and tag_push keys.
• The flag pair refuses to run if apm pack is operating in
  bundle-only mode (no marketplace: block) — tag-on-bundle has no
  natural single-version source.

Out of scope

• Releasing to a non-origin remote via flag. Use git config first.
• GPG configuration help; users wire their own gpgSign.
• Creating tags via the GitHub API instead of git push — keeps the
  command's only side effect inside the local git repo + the user's
  configured remote.
• Per-package tag-pattern overrides surfaced via flag; those already
  live in marketplace.yml under tagPattern.

References

• Existing release gates: apm pack --check-versions (exit code 3),
  --check-clean (exit code 4).
• Versioning strategies: lockstep, tag_pattern, per_package
  (marketplace.versioning.strategy).
• Authoring repo mode discussion: [FEATURE] Authoring-repo mode: publish local .apm/ content via apm pack without self-deploying it during apm install #1474.

Related (same surface, orthogonal problems)

• apm pack --check-clean: rewrite error message to teach the amend+force-with-lease recipe #1381 — apm pack --check-clean error message rewrite. Same
  command family, different feature (error UX vs. new flags). Land
  independently; both improve the release flow.
• [FEATURE] Authoring-repo mode: publish local .apm/ content via apm pack without self-deploying it during apm install #1474 — Authoring-repo mode (self_install: false on apm pack).
  Operates at install time (which files get deployed) while this
  issue operates at pack time (tag creation). Complementary,
  stackable, no conflict.

[danielmeppiel]

Closing as not-planned. After implementation in #1497 and review, the right surface is the existing composition: apm pack --check-versions --check-clean (already shipped) + gh release create v1.2.3 --generate-notes + microsoft/apm-action mode: release (already shipped). See #1497 close comment for the full reasoning. The drift gates this issue motivated remain in place on apm pack — what we're declining is wrapping git tag + git push in APM-specific surface. Follow-up: docs page describing the producer release ritual.