From d7135517e6ee6dbc69c417aa61bcbd80032ef7ef Mon Sep 17 00:00:00 2001 From: Daniel Meppiel <51440732+danielmeppiel@users.noreply.github.com> Date: Tue, 19 May 2026 08:13:51 +0200 Subject: [PATCH] docs: document --check-versions, --check-clean flags and marketplace.versioning schema - Add --check-versions and --check-clean flags to apm pack reference - Add exit codes 3 and 4 for the new release gates - Update --json envelope description to include new version_alignment and drift keys - Add release gates CI examples and versioning strategy config snippet - Add marketplace.versioning section (7.7) to manifest-schema.md covering lockstep / tag_pattern / per_package strategies Triggered by #1365 (feat(pack): add --check-versions and --check-clean release gates) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/reference/cli/pack.md | 29 ++++++++++++++++- .../content/docs/reference/manifest-schema.md | 32 +++++++++++++++++++ 2 files changed, 60 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/reference/cli/pack.md b/docs/src/content/docs/reference/cli/pack.md index 5854094ea..c5ed2b0e6 100644 --- a/docs/src/content/docs/reference/cli/pack.md +++ b/docs/src/content/docs/reference/cli/pack.md @@ -37,7 +37,9 @@ Bundles are target-agnostic. The consumer's project decides where files land at | `--include-prerelease` | off | Marketplace: allow pre-release tags to satisfy version ranges. | | `-m`, `--marketplace FORMATS` | all configured | Comma-separated list of marketplace formats to build. Sentinels: `all` (every configured format), `none` (skip marketplace entirely). | | `--marketplace-path FORMAT=PATH` | manifest default | Override the output path for a specific format. Repeatable. Example: `--marketplace-path codex=./dist/codex.json`. | -| `--json` | off | Emit machine-readable JSON to stdout. All logs move to stderr. Shape: `{ok, dry_run, warnings, errors, marketplace: {outputs: [...]}}`. | +| `--json` | off | Emit machine-readable JSON to stdout. All logs move to stderr. Shape: `{ok, dry_run, warnings, errors, marketplace: {outputs: [...]}, version_alignment, drift}`. The `version_alignment` and `drift` keys are always present; they are `null` when the corresponding gate flag was not passed. | +| `--check-versions` | off | Validate per-package versions against the `marketplace.versioning.strategy` declared in `apm.yml` (`lockstep`, `tag_pattern`, or `per_package`). On misalignment, prints a table of per-package status and exits `3`. Skips with an info note when `apm.yml` has no `marketplace:` block. Composes with `--dry-run` and `--json`. | +| `--check-clean` | off | Regenerate `marketplace.json` into a temp directory and diff it against the committed copy. Exits `4` when any format has drifted. Never writes to the working tree. Composes with `--dry-run` and `--json`. | | `--marketplace-output PATH` | _(hidden)_ | **Deprecated.** Translates to `--marketplace-path claude=PATH` with a stderr warning. Will be removed in v0.15 (see #1318). | | `--legacy-skill-paths` | off | Bundle skills under per-client paths (e.g. `.cursor/skills/`) instead of the converged `.agents/skills/`. Compatibility flag. | | `--target`, `-t VALUE` | auto-detect | **Deprecated.** Recorded as informational `pack.target` metadata only; ignored by `apm install`. Will be removed in a future release. | @@ -92,6 +94,29 @@ apm pack --dry-run apm pack --archive --dry-run -v ``` +### Release gates (CI) + +```bash +# Validate version alignment against declared strategy (exits 3 on mismatch): +apm pack --check-versions --dry-run + +# Confirm committed marketplace.json is not stale (exits 4 on drift): +apm pack --check-clean + +# Run both gates together; structured output for CI step summary: +apm pack --check-versions --check-clean --json +``` + +Configure the versioning strategy in `apm.yml`: + +```yaml +marketplace: + versioning: + strategy: lockstep # all packages must share the same version +``` + +Strategies: `lockstep` (default) -- all package versions match the top-level `version`; `tag_pattern` -- versions are checked against the `build.tagPattern`; `per_package` -- no cross-package version constraint (gate never fails). + ## Output format ### Plugin bundle (`--format plugin`, default) @@ -145,6 +170,8 @@ Configure marketplace artifact paths in `apm.yml`: `marketplace.claude.output` c | `0` | Success. Requested artifacts written (or, with `--dry-run`, planned). | | `1` | Build or runtime error: network failure, ref not found, no tag matches a marketplace range, lockfile read error, or unhandled packer exception. | | `2` | `apm.yml` schema validation error. | +| `3` | `--check-versions` gate failed: at least one package version does not satisfy the declared `marketplace.versioning.strategy`. When both `--check-versions` and `--check-clean` fail, exit `3` takes precedence over `4`. | +| `4` | `--check-clean` gate failed: the committed `marketplace.json` differs from what `apm pack` would generate now. Re-run `apm pack` and commit the updated artifact. | ## Related diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md index 53af8ee3f..bc60d2376 100644 --- a/docs/src/content/docs/reference/manifest-schema.md +++ b/docs/src/content/docs/reference/manifest-schema.md @@ -573,6 +573,7 @@ Overrides exist for the rare case where the published marketplace identity diffe | `output` | `string` | OPTIONAL | `.claude-plugin/marketplace.json` | Output path for the generated marketplace JSON. | | `metadata` | `object` | OPTIONAL | `{}` | Free-form metadata forwarded verbatim to `marketplace.json` (e.g. `homepage`, `support`). | | `build` | `Build` | OPTIONAL | `tagPattern: "v{version}"` | Build configuration for resolving package refs. See Section 7.4. | +| `versioning` | `MarketplaceVersioning` | OPTIONAL | `{strategy: lockstep}` | Release-gate strategy for `apm pack --check-versions`. See Section 7.7. | | `packages` | `list` | OPTIONAL | `[]` | Packages exposed in the marketplace. See Section 7.5. | Unknown keys inside `marketplace:` are rejected at parse time. @@ -658,6 +659,37 @@ marketplace: The legacy standalone `marketplace.yml` (top-level keys, no `marketplace:` wrapper) is still loadable but deprecated; new repositories SHOULD use the in-`apm.yml` form scaffolded by `apm marketplace init`. +### 7.7. `marketplace.versioning` + +The OPTIONAL `versioning` block configures the release-gate strategy enforced by `apm pack --check-versions`. When omitted, the strategy defaults to `lockstep` when `--check-versions` is invoked. + +| Field | Type | Required | Default | Description | +|---|---|---|---|---| +| `strategy` | `enum` | REQUIRED | `lockstep` | One of `lockstep`, `tag_pattern`, or `per_package`. | + +Unknown keys are rejected at parse time. + +**Strategies:** + +| Strategy | Behaviour | +|---|---| +| `lockstep` | All packages listed under `marketplace.packages` MUST share the same `version` value as the top-level `version` field. The most common convention for monorepo marketplaces. | +| `tag_pattern` | Versions are derived from the `build.tagPattern` template; cross-package version equality is not enforced. Suitable for semantic-release workflows where each package tags independently. | +| `per_package` | No cross-package version constraint. The `--check-versions` gate always passes; the field documents intent without enforcement. | + +```yaml +marketplace: + versioning: + strategy: lockstep + packages: + - name: auth + source: contoso/auth + version: "1.2.0" + - name: billing + source: contoso/billing + version: "1.2.0" # must match for lockstep to pass +``` + --- ## 8. Lockfile (`apm.lock.yaml`)