Skip to content

[docs] Update documentation for features from 2026-05-18 #1380

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
danielmeppiel wants to merge 1 commit into from
+60 −1
Closed

[docs] Update documentation for features from 2026-05-18 #1380

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion docs/src/content/docs/reference/cli/pack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand Down
32 changes: 32 additions & 0 deletions docs/src/content/docs/reference/manifest-schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<Package>` | OPTIONAL | `[]` | Packages exposed in the marketplace. See Section 7.5. |

Unknown keys inside `marketplace:` are rejected at parse time.
Expand Down Expand Up @@ -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`. |

Comment on lines +666 to +669
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`)
Expand Down
Loading