diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index d980202..9a90a65 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -20,19 +20,19 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.8.3", + "version": "7.8.4", "source": "./plugins/agentic-engineering" }, { "name": "vibe-coding", "description": "Build a product by conversation alone — a plain-language build companion agent plus skills for needs-to-stack translation, an allowed-stack guardrail, and a jargon-free voice; for people with no technical background", - "version": "1.1.0", + "version": "1.1.1", "source": "./plugins/vibe-coding" }, { "name": "ksail", "description": "KSail CLI expertise and MCP server — create and operate Kubernetes clusters (Kind, K3d, Talos, vCluster, KWOK, EKS) and GitOps workloads declaratively", - "version": "1.0.2", + "version": "1.0.3", "source": "./plugins/ksail" } ] diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json deleted file mode 100644 index d980202..0000000 --- a/.github/plugin/marketplace.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "name": "devantler-plugins", - "metadata": { - "description": "Maintained and curated skills, MCP servers and custom agents bundled by category", - "version": "2.2.0" - }, - "owner": { - "name": "devantler-tech", - "url": "https://github.com/devantler-tech" - }, - "renames": { - "automated-ai-engineer": "agentic-engineering", - "github": "agentic-engineering", - "go": "agentic-engineering", - "gitops-kubernetes": "agentic-engineering", - "engineering-practices": "agentic-engineering", - "frontend-design": "agentic-engineering" - }, - "plugins": [ - { - "name": "agentic-engineering", - "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.8.3", - "source": "./plugins/agentic-engineering" - }, - { - "name": "vibe-coding", - "description": "Build a product by conversation alone — a plain-language build companion agent plus skills for needs-to-stack translation, an allowed-stack guardrail, and a jargon-free voice; for people with no technical background", - "version": "1.1.0", - "source": "./plugins/vibe-coding" - }, - { - "name": "ksail", - "description": "KSail CLI expertise and MCP server — create and operate Kubernetes clusters (Kind, K3d, Talos, vCluster, KWOK, EKS) and GitOps workloads declaratively", - "version": "1.0.2", - "source": "./plugins/ksail" - } - ] -} diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index e34f754..2e99a87 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -196,7 +196,7 @@ jobs: - name: 🧪 Self-test the manifest guard # Proves validate-manifests.sh PASSES a consistent fixture and FAILS each - # drift scenario it exists to catch (malformed/desynced manifests, every + # drift scenario it exists to catch (malformed or duplicate manifests, every # plugin.json completeness rule, every manifest↔plugins lockstep rule), so # a refactor that silently weakens a check is caught here — not by a broken # plugin reaching consumers. Self-contained: throwaway fixtures, no network. diff --git a/.github/workflows/release-please.yaml b/.github/workflows/release-please.yaml index 64ba403..77f0872 100644 --- a/.github/workflows/release-please.yaml +++ b/.github/workflows/release-please.yaml @@ -2,7 +2,7 @@ name: 🚀 Release Please # Cuts marketplace releases with release-please (release-please-config.json and # .release-please-manifest.json). Each push to main updates one reviewable release PR that -# bumps `.metadata.version` in both marketplace manifests. Merging that PR tags `vX.Y.Z` and +# bumps `.metadata.version` in the marketplace manifest. Merging that PR tags `vX.Y.Z` and # publishes the GitHub release with its notes. Per-plugin versions and changelogs stay # author-maintained and are enforced by CI, not by this workflow. diff --git a/.github/workflows/update-agent-skills.yaml b/.github/workflows/update-agent-skills.yaml index 4df0b2b..570dbf4 100644 --- a/.github/workflows/update-agent-skills.yaml +++ b/.github/workflows/update-agent-skills.yaml @@ -151,8 +151,7 @@ jobs: bash "$GITHUB_WORKSPACE/trusted-tools/scripts/plugin-changelog.sh" write origin/main # The publisher independently rejects anything outside this skill's plugin metadata. git add -- '*.desired-state.json' - git add -- .claude-plugin/marketplace.json .github/plugin/marketplace.json \ - 'plugins/*/plugin.json' 'plugins/*/.claude-plugin/plugin.json' \ + git add -- .claude-plugin/marketplace.json 'plugins/*/.claude-plugin/plugin.json' \ 'plugins/*/.codex-plugin/plugin.json' 'plugins/*/CHANGELOG.md' - name: ✍️ Publish one App-signed metadata commit diff --git a/AGENTS.md b/AGENTS.md index bf70596..b0825d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # devantler-tech/agent-plugins -A tool-neutral agent-plugin marketplace that owns the suite's maintained skills and bundles them with curated external skills: `agentic-engineering` carries everything the engineering agents need ([ADR 0017](docs/adr/0017-agentic-engineering-bundles-the-agents-toolbox.md)), `ksail` is the KSail product's plugin, and `vibe-coding` serves building by conversation. One repository owns authoring, validation and delivery across VS Code, GitHub Copilot CLI and Claude Code through two parity-checked manifests. +A tool-neutral agent-plugin marketplace that owns the suite's maintained skills and bundles them with curated external skills: `agentic-engineering` carries everything the engineering agents need ([ADR 0017](docs/adr/0017-agentic-engineering-bundles-the-agents-toolbox.md)), `ksail` is the KSail product's plugin, and `vibe-coding` serves building by conversation. One repository owns authoring, validation and delivery across VS Code, GitHub Copilot CLI and Claude Code through one manifest set that every tool reads. By design the marketplace is **not scoped to skills-only** — a plugin may bundle any agent resource (agent skills today; [MCP](https://modelcontextprotocol.io) servers and custom agents as they prove out @@ -15,19 +15,17 @@ Copilot, and by Cursor, Codex, and Claude (via `CLAUDE.md` → `@AGENTS.md`). ```text .claude-plugin/ -└── marketplace.json # Claude Code marketplace manifest +└── marketplace.json # The marketplace manifest every tool reads .github/ -├── plugin/ -│ └── marketplace.json # Copilot / VS Code marketplace manifest (kept in parity with the Claude one) └── workflows/ ├── ci.yaml # Runs scripts/validate-manifests.sh + lint-scripts (shellcheck + self-test) + agentskills.io spec per skill ├── release-please.yaml # Release PR on each push to main; merging it tags vX.Y.Z and publishes the release └── update-agent-skills.yaml # Daily gh skill update --all; one PR per drifted skill plugins/ └── / - ├── plugin.json # Portable Copilot / CLI plugin manifest ├── .claude-plugin/ - │ └── plugin.json # Equivalent strict Claude marketplace manifest; CI rejects drift + │ └── plugin.json # The plugin manifest every tool reads + ├── .codex-plugin/ # Optional Codex manifest (ADR 0019); mirrors .claude-plugin/plugin.json ├── agents/ # Optional auto-discovered custom agents (*.agent.md) ├── scripts/ # Optional helpers the plugin's agents call, each with a *.test.sh ├── skills/ @@ -50,19 +48,22 @@ docs/scripts.md # What each repository script is for See the [plugin catalogue](docs/plugins.md) and the per-tool [installation instructions](docs/installation.md). -## The two marketplace manifests are the contract - -The repo ships **two marketplace manifests that must stay byte-for-byte in sync** (modulo key order): -[`.github/plugin/marketplace.json`](.github/plugin/marketplace.json) for Copilot / VS Code and -[`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) for Claude Code. CI **diffs the -two** (`jq -S` normalised) and fails on drift or a failed normalization, so a cross-tool install can -never offer different plugins to different tools. **Any change to the plugin set updates both manifests in the same PR** — -they are the source of truth for what the marketplace offers. CI also checks each manifest entry against -the **filesystem**: every plugin must have a matching portable `plugins//plugin.json` (with the -same `name`/`description`/`version` and `source` `./plugins/`) plus an equivalent -`plugins//.claude-plugin/plugin.json`. Claude Desktop's remote Personal-marketplace ingestion -requires the canonical nested path in strict mode even though the local Claude CLI and Copilot accept -the top-level manifest; CI normalises and compares both copies so they cannot drift. No +## One manifest set is the contract + +The repo ships **one marketplace manifest**, [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json), +and **one manifest per plugin**, `plugins//.claude-plugin/plugin.json`. VS Code, the GitHub +Copilot CLI, Claude Code, Claude Desktop and Codex all read these files, so a cross-tool install can +never offer different plugins to different tools. The only other manifest is a plugin's optional +Codex-specific `.codex-plugin/plugin.json` (ADR 0019), which must repeat the plugin manifest apart from +Codex's own fields. [Installation](docs/installation.md#one-manifest-set-for-every-tool) lists the path +each tool reads. CI refuses a copy at any other path VS Code checks (`marketplace.json`, +`.plugin/marketplace.json`, `.github/plugin/marketplace.json`, a plugin's `plugin.json` or +`.plugin/plugin.json`): VS Code would read most of them before the canonical file, and any copy can +drift. The marketplace manifest is the source of truth for what the marketplace offers. CI also checks +each entry against the **filesystem**: every plugin must have a matching +`plugins//.claude-plugin/plugin.json` with the same `name`/`description`/`version`, and the +entry's `source` must be `./plugins/`. Claude Desktop's remote Personal-marketplace ingestion +requires that canonical nested path in strict mode. No `plugins//` may exist without a manifest entry. CI also checks the human-facing **plugin catalogue table** against the filesystem: every plugin has a table row (and vice versa) and each row's **Resources** column matches that plugin's bundled resources — its @@ -71,7 +72,7 @@ custom-agent entries in an optional `plugins//agents/` — so the catalogu drift from what ships either. Marketplace plugin names are also a persisted consumer contract. Once a plugin is renamed or removed, -record that transition in the top-level **`renames` map in both manifests and never delete the entry**: +record that transition in the marketplace manifest's top-level **`renames` map and never delete the entry**: Claude Code uses this append-only history to migrate qualified installed-plugin keys during marketplace refresh. Add the same transition to the append-only [`scripts/marketplace-rename-history.json`](scripts/marketplace-rename-history.json) baseline. CI rejects @@ -125,13 +126,12 @@ The daily updater still refreshes external skills independently with no lockfile ## Conventions -1. **Two manifests in parity.** Every plugin appears in **both** `marketplace.json` files with the same - `name`/`description`/`version`/`source`; CI enforces the diff. Edit both together. -2. **Plugin layout.** A plugin is a directory under `plugins/` with a portable `plugin.json` and an - equivalent `.claude-plugin/plugin.json` (kebab-case `name`, a visible text - `description`, and a canonical stable cache `version`). Keep both normalised JSON documents semantically identical: the - top-level file serves Copilot/CLI consumers, while strict Claude remote ingestion requires the - nested canonical path. The plugin declares **at least one resource**: +1. **One manifest set.** Every plugin appears in `.claude-plugin/marketplace.json` with the same + `name`/`description`/`version` as its `.claude-plugin/plugin.json` and `source` `./plugins/`. + Never add a second marketplace or plugin manifest; a Codex manifest is the one exception. +2. **Plugin layout.** A plugin is a directory under `plugins/` with a `.claude-plugin/plugin.json` + (kebab-case `name`, a visible text `description`, and a canonical stable cache `version`). The + plugin declares **at least one resource**: a `skills/` subdirectory, a bundled `.mcp.json` (MCP servers), and/or an `agents/` directory. Every skill directory and agent file uses the canonical `skills/` or `agents/` layout. The shipped manifests omit component fields for automatic discovery. This marketplace's portable contract accepts optional arrays of @@ -143,8 +143,8 @@ The daily updater still refreshes external skills independently with no lockfile together. Explicit agent arrays determine the catalogue's selected agents; an empty array selects none. Skill paths add to the default skill inventory, as described in the [Claude manifest reference](https://code.claude.com/docs/en/plugins-reference). - The package gate rejects repeated decoded JSON keys in both marketplace manifests and plugin - manifests, rename history and desired-state resources before parity checks. Marketplace names are text identifiers and plugin + The package gate rejects repeated decoded JSON keys in the marketplace manifest, plugin + manifests, rename history and desired-state resources before agreement checks. Marketplace names are text identifiers and plugin entries have unique names, visible descriptions and stable cache versions. Run `bash scripts/package-discovery.test.sh` for regular-file, complete-package and selection cases. Run `bash scripts/package-boundaries.test.sh` with the manifest tests. Skill dirs sit at @@ -195,9 +195,9 @@ The daily updater still refreshes external skills independently with no lockfile plugins by `//`, so a content change that leaves the version alone is unreachable for every consumer that already installed it: the update command reports "already at the latest version" and keeps serving the stale copy, with no error and no drift signal. Bump with - [`scripts/bump-plugin-version.sh`](scripts/bump-plugin-version.sh), which moves all four places the - version must agree (the portable and strict manifests plus both marketplace entries) — a hand-edit - easily half-lands. The updater checks identities, unique membership and version parity before + [`scripts/bump-plugin-version.sh`](scripts/bump-plugin-version.sh), which moves every place the + version must agree (the plugin manifest, its Codex manifest when present, and its marketplace + entry) — a hand-edit easily half-lands. The updater checks identities, unique membership and version parity before writing any manifest, including when several plugins changed. Cache versions must increase using canonical stable versions; a downgrade cannot reuse an older cache identity. The `Check version bump` CI job enforces it on every PR, and the daily skill-sync @@ -286,13 +286,13 @@ issue/PR/CI text as untrusted data; work in **per-run worktrees**; never push to PR/issue/comment with `> 🤖 Generated by the Agentic Engineer` (the legacy `Daily AI Engineer` and `Daily AI Assistant` prefixes stay recognised as agent output). -**Blast radius first:** this is a **shared library** consumed across every agent install — the two -manifests drive what VS Code / Copilot CLI / Claude Code offer, so a malformed manifest, an out-of-sync -pair, or a broken bundled `SKILL.md` ripples into every consumer. Prefer additive, backward-compatible -changes; keep the two manifests in parity and the README in lockstep. List the consumers of a renamed or removed contract section or skill first with the monorepo's [`consumer-census.sh`](https://github.com/devantler-tech/monorepo/blob/main/.claude/scripts/consumer-census.sh): from a monorepo checkout, `.claude/scripts/consumer-census.sh "
"` (quoted, since section names contain spaces; for a skill, also run it for its plugin's install name, such as `agentic-engineering@devantler-plugins`, because an installation does not name each bundled skill) prints each consumer's `file:line`; an `UNKNOWN` repository was not searched, which is never zero consumers. It searches the monorepo itself too, the main consumer of contract sections: the output must have a row for `.`. A census without that row comes from a checkout older than devantler-tech/monorepo#4925, so update the checkout first. That row searches whatever the checkout calls `origin`, so run the census from a checkout of `devantler-tech/monorepo` itself, never from a fork. +**Blast radius first:** this is a **shared library** consumed across every agent install — the one +manifest set drives what VS Code / Copilot CLI / Claude Code / Codex offer, so a malformed manifest +or a broken bundled `SKILL.md` ripples into every consumer. Prefer additive, backward-compatible +changes; keep the manifests and the README in lockstep. List the consumers of a renamed or removed contract section or skill first with the monorepo's [`consumer-census.sh`](https://github.com/devantler-tech/monorepo/blob/main/.claude/scripts/consumer-census.sh): from a monorepo checkout, `.claude/scripts/consumer-census.sh "
"` (quoted, since section names contain spaces; for a skill, also run it for its plugin's install name, such as `agentic-engineering@devantler-plugins`, because an installation does not name each bundled skill) prints each consumer's `file:line`; an `UNKNOWN` repository was not searched, which is never zero consumers. It searches the monorepo itself too, the main consumer of contract sections: the output must have a row for `.`. A census without that row comes from a checkout older than devantler-tech/monorepo#4925, so update the checkout first. That row searches whatever the checkout calls `origin`, so run the census from a checkout of `devantler-tech/monorepo` itself, never from a fork. **Validate before any PR:** run the steps in [docs/validation.md](docs/validation.md) (`./scripts/validate-manifests.sh`, -spec-validate each skill, `actionlint` changed workflows). No app build here — manifest parity, +spec-validate each skill, `actionlint` changed workflows). No app build here — manifest agreement, `plugin.json` validity, `SKILL.md` spec-conformance, and pinned workflows are the gate. Never weaken a security control or a check to pass. @@ -300,7 +300,7 @@ security control or a check to pass. - **Curate the marketplace:** curate a high-quality external skill into the plugin whose users need it — the agents' toolbox goes into `agentic-engineering` (install external sources with `gh skill install`, never hand-copy, and never repackage another project's plugin); retire a stale - resource — always editing **both** manifests and the README together. + resource — always editing the marketplace manifest and the README together. - **Maintain authored skills** in their canonical `plugins//skills//` source, including resources and tests. - **Keep external skills fresh:** let the daily `update-agent-skills` PR flow through; fix failed CI. Never hand-edit an external synchronized copy: fix its provenance-recorded upstream first. - **Tool-neutral rescope** ([#7](https://github.com/devantler-tech/agent-plugins/issues/7)): de-Copilot-brand diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a21691..1d634f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,8 +40,8 @@ prove that a plugin was loaded successfully in your assistant. Maintained first-party skills are authored in `plugins//skills//`, including their resources and tests. They carry no install metadata in this source tree. External synchronized skills record their owner in `metadata.github-repo`: fix those upstream, then install the reviewed result with `gh skill install` (GitHub CLI 2.90 or later). Maintained first-party skills, bundle membership and marketplace documentation are authored here. External skill trees remain owned by the upstream in their install metadata. If you change shipped plugin -content, update both marketplace manifests, the portable and strict plugin manifests, and the -catalogue together. Use `bash scripts/bump-plugin-version.sh minor` for an additive skill. +content, update the marketplace manifest, the plugin's `.claude-plugin/plugin.json` (and its +`.codex-plugin/plugin.json`, when it has one) and the catalogue together. Use `bash scripts/bump-plugin-version.sh minor` for an additive skill. For a skill addition or sync, commit the skill trees first: the release-note writer reads committed source revisions and external provenance, not unstaged files. Then run `bash scripts/plugin-changelog.sh write origin/main`, inspect its output, and include the generated changelog in a follow-up commit before opening the PR. diff --git a/README.md b/README.md index 5d56995..99fd558 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ In **Claude Code**, add the marketplace and install the agentic engineering bund /plugin install agentic-engineering@devantler-plugins ``` -Using another tool? Follow the [VS Code](docs/installation.md#vs-code), [Copilot CLI](docs/installation.md#copilot-cli), [Claude Code](docs/installation.md#claude-code), or [skills-only installation guide](docs/installation.md#any-other-agent--skills-only-via-npx-skills). +Using another tool? Follow the [VS Code](docs/installation.md#vs-code), [Copilot CLI](docs/installation.md#copilot-cli), [Claude Code](docs/installation.md#claude-code), or [skills-only installation guide](docs/installation.md#any-other-agent--skills-only-via-npx-skills). Every tool reads the same manifests; the guide lists [which file each one reads](docs/installation.md#one-manifest-set-for-every-tool). ## Choose a bundle diff --git a/docs/installation.md b/docs/installation.md index 1ea6bb9..091e9ad 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,5 +1,23 @@ # Installation +## One manifest set for every tool + +The repository ships one marketplace manifest, [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json), +and one manifest per plugin, `plugins//.claude-plugin/plugin.json`. Every supported tool reads +those files: + +| Tool | Marketplace manifest it reads | Plugin manifest it reads | +| --- | --- | --- | +| VS Code | the first of `marketplace.json`, `.plugin/marketplace.json`, `.github/plugin/marketplace.json` and `.claude-plugin/marketplace.json` | the first of `.plugin/plugin.json`, `.claude-plugin/plugin.json` and `plugin.json` | +| GitHub Copilot CLI | `.claude-plugin/marketplace.json` | `.claude-plugin/plugin.json` | +| Claude Code and Claude Desktop | `.claude-plugin/marketplace.json` | `.claude-plugin/plugin.json` | +| Codex | `.claude-plugin/marketplace.json` | `.codex-plugin/plugin.json` when a plugin ships one, otherwise `.claude-plugin/plugin.json` | + +The repository has none of the other paths VS Code checks, so VS Code also reads the +`.claude-plugin` files. `scripts/validate-manifests.sh` refuses a copy at any of those paths: VS +Code would read most of them before the canonical file, and any copy can drift from it. The only +second manifest is Codex's own, described [below](#codex). + ## VS Code Add the marketplace to your settings: @@ -55,7 +73,7 @@ Codex reads a plugin's `.codex-plugin/plugin.json` before its `.claude-plugin/pl use: iCloud Mail, iCloud Calendar, LinkedIn and Codex Security Cloud, all optional, listed in its [`.app.json`](../plugins/agentic-engineering/.app.json). Each still needs your own sign-in. The `ksail` plugin ships one for its OpenAI plugin directory listing; it offers no apps. -`scripts/validate-manifests.sh` keeps each Codex manifest identical to the portable one apart from its +`scripts/validate-manifests.sh` keeps each Codex manifest identical to `.claude-plugin/plugin.json` apart from its component paths, app list and listing, and `scripts/bump-plugin-version.sh` moves its version with the others. diff --git a/docs/marketplace-releases.md b/docs/marketplace-releases.md index 678967a..00f1b38 100644 --- a/docs/marketplace-releases.md +++ b/docs/marketplace-releases.md @@ -1,7 +1,7 @@ # Marketplace releases A marketplace version describes the whole catalogue at one commit of `main`. It is the -`.metadata.version` in both marketplace manifests, and each release is tagged `vX.Y.Z`. Each plugin +`.metadata.version` in the marketplace manifest, and each release is tagged `vX.Y.Z`. Each plugin keeps its own version, which is its runtime cache key; the marketplace version does not replace it. ## How a release happens @@ -11,9 +11,8 @@ Commit titles that squash merges leave on `main`. The [Release Please workflow](../.github/workflows/release-please.yaml) runs on every push to `main`: 1. It opens or updates one **release PR**. The PR moves `.metadata.version` in - [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) and - [`.github/plugin/marketplace.json`](../.github/plugin/marketplace.json) together, and its body holds - the release notes. The repository's GitHub App opens it, so normal CI runs on it. + [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json), and its body holds the + release notes. The repository's GitHub App opens it, so normal CI runs on it. 2. The release PR is an ordinary pull request. Review it like any other, and merge it when the release should go out. Until then it keeps collecting the changes that land on `main`. 3. Merging it tags the merge commit `vX.Y.Z` and publishes a GitHub release with the same notes. diff --git a/docs/scripts.md b/docs/scripts.md index dd4accc..0b3c4c2 100644 --- a/docs/scripts.md +++ b/docs/scripts.md @@ -7,7 +7,7 @@ complete inventory; read a script's header for its arguments and safeguards. |---|---| | Check a change | Follow the [validation steps](validation.md), including dependency installation | | Review plugin use and usefulness | [Plugin effectiveness](plugin-effectiveness.md) and `bash scripts/plugin-scorecard.sh`; reads native exports and benchmark artifacts without configuring telemetry | -| Update versions and release notes | Use [bump-plugin-version.sh](../scripts/bump-plugin-version.sh) and add a matching changelog entry; skill syncs use [plugin-changelog.sh write](../scripts/plugin-changelog.sh) | +| Update versions and release notes | Use [bump-plugin-version.sh](../scripts/bump-plugin-version.sh), which moves the version in the plugin manifest, its Codex manifest and its marketplace entry, and add a matching changelog entry; skill syncs use [plugin-changelog.sh write](../scripts/plugin-changelog.sh) | | Refresh generated resource digests | [refresh-desired-state-digests.sh](../scripts/refresh-desired-state-digests.sh) | | Synchronize one curated plugin | Dispatch [Update Agent Skills](../.github/workflows/update-agent-skills.yaml) with `agentic-engineering`; [skill-update-scope.sh](../scripts/skill-update-scope.sh) resolves only declared selections before the normal per-skill updater runs. Default and scheduled `all` updates still cover the full catalogue. | | Cut a marketplace release | No script: merge the release-please release PR, as the [release guide](marketplace-releases.md) explains | diff --git a/docs/skill-lifecycle.md b/docs/skill-lifecycle.md index bab6dd0..200d1ce 100644 --- a/docs/skill-lifecycle.md +++ b/docs/skill-lifecycle.md @@ -91,7 +91,7 @@ and its scenarios are on #641. ## What CI checks, and what it does not -Checked on every pull request: the two marketplace manifests agree, every skill folder is +Checked on every pull request: the one marketplace manifest matches its plugins, every skill folder is catalogued, external skills keep their provenance and are not edited, every bundled skill has a licence record, each `SKILL.md` validates against the open skill format, and a changed plugin has a changed version. [`validation.md`](validation.md) has the commands. diff --git a/docs/tool-ownership.md b/docs/tool-ownership.md index d3a9374..2901e73 100644 --- a/docs/tool-ownership.md +++ b/docs/tool-ownership.md @@ -40,7 +40,7 @@ Their documented interfaces are supported here; none establishes an independent | Candidate | Observed caller and task | Ownership rationale | |---|---|---| | [`validate-manifests.sh`](../scripts/validate-manifests.sh) | CI and maintainer instructions validate manifests, provenance and resource parity | Marketplace schema and consumer promises belong here. A generic schema checker does not replace the parity and provenance policy. | -| [`bump-plugin-version.sh`](../scripts/bump-plugin-version.sh) | Skill-update workflow and maintainer invocation move four related manifests together | Keep version selection with the four manifests. The assessment found failed Git observations could be accepted; [#319](https://github.com/devantler-tech/agent-plugins/issues/319) tracks the repair. | +| [`bump-plugin-version.sh`](../scripts/bump-plugin-version.sh) | Skill-update workflow and maintainer invocation move the plugin and marketplace manifests together | Keep version selection with those manifests. The assessment found failed Git observations could be accepted; [#319](https://github.com/devantler-tech/agent-plugins/issues/319) tracks the repair. | | [`check-plugin-version-bump.sh`](../scripts/check-plugin-version-bump.sh) | CI compares a change with its merge base and requires changed plugin content to move version | The cache/version promise is marketplace policy. The same discovery failure is covered by #319; a language migration would not itself correct it. | | [`guard-bundled-skill-edits.sh`](../scripts/guard-bundled-skill-edits.sh) | PR CI checks changed paths against base provenance and the authorized sync writer | Retain the source-ownership and writer rules here. Skill installation transport cannot decide this repository's editing exemption. | | [`guard-gh-json-fields.sh`](../scripts/guard-gh-json-fields.sh) | CI checks agent-readable guidance for unsupported GitHub CLI fields | Keep the guidance policy and content-bound exemptions here; delegate Go syntax decoding to the adjacent parser. | diff --git a/docs/validation.md b/docs/validation.md index 678a328..bc1167a 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -46,9 +46,9 @@ npm ci --ignore-scripts --no-audit --no-fund # Offline native usage attribution and benchmark score reporting. bash scripts/plugin-scorecard.test.sh -# 1. Marketplace parity, portable ↔ strict-Claude plugin.json parity, catalogue table, -# desired-state resources, and skill provenance — the exact checks CI's -# "Validate manifests" job runs. +# 1. One manifest set (no duplicate marketplace or plugin manifest), marketplace ↔ plugin.json +# agreement, catalogue table, desired-state resources, and skill provenance — the exact +# checks CI's "Validate manifests" job runs. ./scripts/validate-manifests.sh # Every bundled skill keeps its own license (CI's "Check bundled skill licenses" step). A third-party # skill needs a row and a `## /` section with its copyright notice and license text in @@ -121,6 +121,11 @@ asserted `.skills == "skills/"` in every `plugin.json`, long after the conventio that field (skills are auto-discovered), so following this document reported all 8 plugins broken while CI was green (#65). +The repository keeps one manifest set: `.claude-plugin/marketplace.json` and each plugin's +`.claude-plugin/plugin.json`, plus an optional Codex `.codex-plugin/plugin.json`. Step 1 refuses a +copy at any other path VS Code reads; [Installation](installation.md#one-manifest-set-for-every-tool) +lists the path each tool reads. + The validator retains marketplace entries, catalogue rows, desired-state resources, runtime assets, schedule sources and skill provenance only after their inventory commands succeed. Failed empty or partial observations refuse validation; complete empty selections remain valid where resources are diff --git a/plugins/agentic-engineering/.claude-plugin/plugin.json b/plugins/agentic-engineering/.claude-plugin/plugin.json index ef40a7f..410d39e 100644 --- a/plugins/agentic-engineering/.claude-plugin/plugin.json +++ b/plugins/agentic-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.8.3", + "version": "7.8.4", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/.codex-plugin/plugin.json b/plugins/agentic-engineering/.codex-plugin/plugin.json index 1cb7b38..f697efb 100644 --- a/plugins/agentic-engineering/.codex-plugin/plugin.json +++ b/plugins/agentic-engineering/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentic-engineering", "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.8.3", + "version": "7.8.4", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/agentic-engineering/CHANGELOG.md b/plugins/agentic-engineering/CHANGELOG.md index dfa74b0..8432554 100644 --- a/plugins/agentic-engineering/CHANGELOG.md +++ b/plugins/agentic-engineering/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog — `agentic-engineering` +## 7.8.4 — 2026-11-14 + +**Changed** — remove the duplicate top-level `plugin.json`. Every supported tool reads +`.claude-plugin/plugin.json` instead, so installs and updates need no action. + ## 7.8.3 — 2026-11-14 **Changed** — sync `upgrade-stripe` from `https://github.com/stripe/ai` at `refs/heads/main`. diff --git a/plugins/agentic-engineering/plugin.json b/plugins/agentic-engineering/plugin.json deleted file mode 100644 index ef40a7f..0000000 --- a/plugins/agentic-engineering/plugin.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "name": "agentic-engineering", - "description": "The autonomous engineering system for repository portfolios and everything its agents need — engineer, read-only surveyor, meta-engineer and Flux troubleshooter agents; portfolio, product, spend and improvement workflows; GitHub, CodeRabbit review, security, library documentation, Go, Kubernetes, Flux, Talos, SvelteKit frontend, Stripe payments, engineering-practice, design, product-management, marketing, finance and productivity skills; and the MCP servers they use; configured by the consumer AGENTS.md", - "version": "7.8.3", - "author": { - "name": "devantler-tech", - "url": "https://github.com/devantler-tech" - }, - "keywords": [ - "agents", - "agentic", - "autonomous-engineer", - "ai-engineer", - "portfolio-maintenance", - "product-engineering", - "self-improvement", - "agent-improvement", - "meta-engineer", - "agent-instructions", - "skills", - "run-loop", - "draft-pr", - "github", - "security", - "go", - "kubernetes", - "gitops", - "flux", - "talos", - "mcp", - "svelte", - "sveltekit", - "frontend", - "coderabbit", - "code-review", - "context7", - "documentation", - "stripe", - "payments", - "design", - "product-management", - "marketing", - "finance", - "productivity", - "connectors" - ] -} diff --git a/plugins/ksail/.claude-plugin/plugin.json b/plugins/ksail/.claude-plugin/plugin.json index 74d1a27..ae59d6f 100644 --- a/plugins/ksail/.claude-plugin/plugin.json +++ b/plugins/ksail/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ksail", "description": "KSail CLI expertise and MCP server — create and operate Kubernetes clusters (Kind, K3d, Talos, vCluster, KWOK, EKS) and GitOps workloads declaratively", - "version": "1.0.2", + "version": "1.0.3", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/ksail/.codex-plugin/plugin.json b/plugins/ksail/.codex-plugin/plugin.json index a8b3e32..d0674c3 100644 --- a/plugins/ksail/.codex-plugin/plugin.json +++ b/plugins/ksail/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ksail", "description": "KSail CLI expertise and MCP server — create and operate Kubernetes clusters (Kind, K3d, Talos, vCluster, KWOK, EKS) and GitOps workloads declaratively", - "version": "1.0.2", + "version": "1.0.3", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/ksail/CHANGELOG.md b/plugins/ksail/CHANGELOG.md index fd7369c..acba1c0 100644 --- a/plugins/ksail/CHANGELOG.md +++ b/plugins/ksail/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog — `ksail` +## 1.0.3 — 2026-11-14 + +**Changed** — remove the duplicate top-level `plugin.json`. Every supported tool reads +`.claude-plugin/plugin.json` instead, so installs and updates need no action. + ## 1.0.2 — 2026-11-07 **Changed** — sync `ksail` from `https://github.com/devantler-tech/ksail` at `refs/tags/v7.212.9`. diff --git a/plugins/ksail/plugin.json b/plugins/ksail/plugin.json deleted file mode 100644 index 74d1a27..0000000 --- a/plugins/ksail/plugin.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "name": "ksail", - "description": "KSail CLI expertise and MCP server — create and operate Kubernetes clusters (Kind, K3d, Talos, vCluster, KWOK, EKS) and GitOps workloads declaratively", - "version": "1.0.2", - "author": { - "name": "devantler-tech", - "url": "https://github.com/devantler-tech" - }, - "license": "PolyForm-Shield-1.0.0", - "homepage": "https://ksail.devantler.tech", - "repository": "https://github.com/devantler-tech/ksail", - "keywords": [ - "kubernetes", - "k8s", - "gitops", - "ksail", - "kind", - "k3d", - "talos", - "vcluster", - "eks", - "flux", - "argocd", - "mcp" - ] -} diff --git a/plugins/vibe-coding/.claude-plugin/plugin.json b/plugins/vibe-coding/.claude-plugin/plugin.json index 6fbfc25..e90e731 100644 --- a/plugins/vibe-coding/.claude-plugin/plugin.json +++ b/plugins/vibe-coding/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "vibe-coding", "description": "Build a product by conversation alone — a plain-language build companion agent plus skills for needs-to-stack translation, an allowed-stack guardrail, and a jargon-free voice; for people with no technical background", - "version": "1.1.0", + "version": "1.1.1", "author": { "name": "devantler-tech", "url": "https://github.com/devantler-tech" diff --git a/plugins/vibe-coding/CHANGELOG.md b/plugins/vibe-coding/CHANGELOG.md index f5d0241..2af8955 100644 --- a/plugins/vibe-coding/CHANGELOG.md +++ b/plugins/vibe-coding/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 1.1.1 — 2026-11-14 + +**Changed** — remove the duplicate top-level `plugin.json`. Every supported tool reads +`.claude-plugin/plugin.json` instead, so installs and updates need no action. + ## 1.1.0 2026-11-01 diff --git a/plugins/vibe-coding/plugin.json b/plugins/vibe-coding/plugin.json deleted file mode 100644 index 6fbfc25..0000000 --- a/plugins/vibe-coding/plugin.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "name": "vibe-coding", - "description": "Build a product by conversation alone — a plain-language build companion agent plus skills for needs-to-stack translation, an allowed-stack guardrail, and a jargon-free voice; for people with no technical background", - "version": "1.1.0", - "author": { - "name": "devantler-tech", - "url": "https://github.com/devantler-tech" - }, - "keywords": [ - "vibe-coding", - "conversational", - "non-technical", - "plain-language", - "no-code-experience", - "guardrail", - "stack-map", - "product-building" - ] -} diff --git a/release-please-config.json b/release-please-config.json index f0fda87..c1d8464 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -11,11 +11,6 @@ "type": "json", "path": ".claude-plugin/marketplace.json", "jsonpath": "$.metadata.version" - }, - { - "type": "json", - "path": ".github/plugin/marketplace.json", - "jsonpath": "$.metadata.version" } ] } diff --git a/scripts/bump-plugin-version.sh b/scripts/bump-plugin-version.sh index ea949ae..05f939b 100755 --- a/scripts/bump-plugin-version.sh +++ b/scripts/bump-plugin-version.sh @@ -1,10 +1,10 @@ #!/usr/bin/env bash # Bump a plugin's version across all the manifests that must agree. # -# A plugin's version lives in four places — the portable manifest, the strict Claude manifest, -# and one entry in each of the two marketplace manifests — plus a Codex manifest when the plugin -# ships one, and validate-manifests.sh fails if they disagree. Doing that by hand is four edits and an easy way to ship a half-bumped plugin, -# so this is the one supported way to move a version. +# A plugin's version lives in its .claude-plugin/plugin.json and its entry in the +# .claude-plugin/marketplace.json marketplace manifest, plus a Codex manifest when the plugin +# ships one, and validate-manifests.sh fails if they disagree. Doing that by hand is an easy +# way to ship a half-bumped plugin, so this is the one supported way to move a version. # # Consumers cache plugins by version, so a content change that leaves the version untouched # never reaches them; check-plugin-version-bump.sh is the gate that catches it, and this is the @@ -20,7 +20,6 @@ set -euo pipefail CLAUDE_MANIFEST=".claude-plugin/marketplace.json" -COPILOT_MANIFEST=".github/plugin/marketplace.json" # shellcheck source=scripts/plugin-version.lib.sh . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/plugin-version.lib.sh" @@ -34,27 +33,25 @@ plugin_version_git_context work=$(mktemp -d) trap 'rm -rf "$work"' EXIT : > "$work/changes" -for directory in .claude-plugin .github .github/plugin; do - if [ ! -d "$directory" ] || [ -L "$directory" ]; then - echo '::error::Manifest parent must be a real checkout directory.' >&2; exit 1 - fi -done -for manifest in "$CLAUDE_MANIFEST" "$COPILOT_MANIFEST"; do - [ -f "$manifest" ] && [ ! -L "$manifest" ] || exit 1 - snapshot="$work/$(basename "$(dirname "$manifest")").original" - cp "$manifest" "$snapshot" - json_object_unique "$snapshot" || { echo '::error::Marketplace declarations must be unambiguous; no manifests were changed.' >&2; exit 1; } - jq -es 'length==1 and (.[0] | type == "object" and (.plugins | type == "array"))' "$snapshot" >/dev/null || exit 1 - cp "$snapshot" "$work/$(basename "$(dirname "$manifest")").json" -done +if [ ! -d .claude-plugin ] || [ -L .claude-plugin ]; then + echo '::error::Manifest parent must be a real checkout directory.' >&2; exit 1 +fi +[ -f "$CLAUDE_MANIFEST" ] && [ ! -L "$CLAUDE_MANIFEST" ] || exit 1 +# The marketplace snapshot is the comparison original; the staged copy collects every increment. +snapshot="$work/marketplace.original" +staged_marketplace="$work/marketplace.json" +cp "$CLAUDE_MANIFEST" "$snapshot" +json_object_unique "$snapshot" || { echo '::error::Marketplace declarations must be unambiguous; no manifests were changed.' >&2; exit 1; } +jq -es 'length==1 and (.[0] | type == "object" and (.plugins | type == "array"))' "$snapshot" >/dev/null || exit 1 +cp "$snapshot" "$staged_marketplace" -# Validate one plugin's manifest parity and stage its increment without changing the checkout. +# Validate one plugin's manifest agreement and stage its increment without changing the checkout. plan_one() { - local name="$1" level="$2" dir="plugins/$1" current='' new manifest staged entry observed original + local name="$1" level="$2" dir="plugins/$1" current='' new manifest entry observed original local -a manifests [[ "$name" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || { echo '::error::Invalid plugin identity.' >&2; return 1; } plugin_version_local_parents "$name" || return 1 - manifests=("$dir/plugin.json" "$dir/.claude-plugin/plugin.json") + manifests=("$dir/.claude-plugin/plugin.json") # Codex reads its own manifest before the Claude one when a plugin ships it, so it moves in step. if [ -e "$dir/.codex-plugin" ] || [ -L "$dir/.codex-plugin" ]; then if [ ! -d "$dir/.codex-plugin" ] || [ -L "$dir/.codex-plugin" ]; then @@ -74,15 +71,12 @@ plan_one() { return 1 } done - for manifest in "$CLAUDE_MANIFEST" "$COPILOT_MANIFEST"; do - staged="$work/$(basename "$(dirname "$manifest")").json" - jq -e --arg n "$name" --arg v "$current" ' + jq -e --arg n "$name" --arg v "$current" ' [.plugins[] | select(.name == $n)] | length == 1 and - (.[0] | .version == $v and .source == ("./plugins/" + $n))' "$staged" >/dev/null || { - echo "::error::$manifest: expected one matching plugin at the same version; no manifests were changed." >&2 - return 1 - } - done + (.[0] | .version == $v and .source == ("./plugins/" + $n))' "$staged_marketplace" >/dev/null || { + echo "::error::$CLAUDE_MANIFEST: expected one matching plugin at the same version; no manifests were changed." >&2 + return 1 + } # Changed-since must validate even a plugin already bumped on the branch. if [ "$level" = keep ]; then return 0; fi new=$(plugin_version_next "$current" "$level") || return 1 @@ -92,11 +86,8 @@ plan_one() { jq --arg v "$new" '.version = $v' "$original" > "$entry" || return 1 printf '%s\0%s\0%s\0' "$manifest" "$entry" "$original" >> "$work/changes" done - for manifest in "$CLAUDE_MANIFEST" "$COPILOT_MANIFEST"; do - staged="$work/$(basename "$(dirname "$manifest")").json" - jq --arg n "$name" --arg v "$new" '.plugins |= map(if .name == $n then .version = $v else . end)' "$staged" > "$work/next" || return 1 - mv "$work/next" "$staged" - done + jq --arg n "$name" --arg v "$new" '.plugins |= map(if .name == $n then .version = $v else . end)' "$staged_marketplace" > "$work/next" || return 1 + mv "$work/next" "$staged_marketplace" echo "✓ $name $current → $new" } @@ -171,11 +162,7 @@ main() { plan_one "$p" "$level" done # Only complete plans are installed; a bad later input cannot half-bump a plugin. - local destination staged - for destination in "$CLAUDE_MANIFEST" "$COPILOT_MANIFEST"; do - staged="$work/$(basename "$(dirname "$destination")").json" - printf '%s\0%s\0%s\0' "$destination" "$staged" "$work/$(basename "$(dirname "$destination")").original" >> "$work/changes" - done + printf '%s\0%s\0%s\0' "$CLAUDE_MANIFEST" "$staged_marketplace" "$snapshot" >> "$work/changes" atomic_write_batch "$work/changes" } diff --git a/scripts/bump-plugin-version.test.sh b/scripts/bump-plugin-version.test.sh index 8cc3a52..09ff595 100755 --- a/scripts/bump-plugin-version.test.sh +++ b/scripts/bump-plugin-version.test.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # Self-test for bump-plugin-version.sh. # -# Proves the helper moves the version in ALL FOUR manifests that must agree (a partial bump +# Proves the helper moves the version in EVERY manifest that must agree (a partial bump # would fail validate-manifests.sh downstream), that each bump level is arithmetically right, # that --changed-since bumps exactly the plugins whose content moved and is idempotent on a # re-run, and that it fails closed on a bad plugin, a bad level, and a non-semver version. @@ -23,7 +23,6 @@ make_plugin() { mkdir -p "$root/plugins/$name/.claude-plugin" "$root/plugins/$name/skills/example-skill" local pj pj=$(printf '{"name":"%s","description":"%s plugin","version":"%s"}' "$name" "$name" "$version") - printf '%s\n' "$pj" > "$root/plugins/$name/plugin.json" printf '%s\n' "$pj" > "$root/plugins/$name/.claude-plugin/plugin.json" printf -- '---\nname: example-skill\n---\n%s\n' "$body" \ > "$root/plugins/$name/skills/example-skill/SKILL.md" @@ -31,7 +30,7 @@ make_plugin() { make_repo() { local root="$1" - mkdir -p "$root/.claude-plugin" "$root/.github/plugin" + mkdir -p "$root/.claude-plugin" local manifest='{ "name": "devantler-plugins", "plugins": [ @@ -40,7 +39,6 @@ make_repo() { ] }' printf '%s\n' "$manifest" > "$root/.claude-plugin/marketplace.json" - printf '%s\n' "$manifest" > "$root/.github/plugin/marketplace.json" make_plugin "$root" alpha "1.2.3" make_plugin "$root" beta "1.2.3" git -C "$root" init --quiet --initial-branch=main @@ -56,13 +54,11 @@ make_repo() { # Every place a version must agree. versions_of() { local root="$1" name="$2" - jq -r '.version' "$root/plugins/$name/plugin.json" jq -r '.version' "$root/plugins/$name/.claude-plugin/plugin.json" if [ -f "$root/plugins/$name/.codex-plugin/plugin.json" ]; then jq -r '.version' "$root/plugins/$name/.codex-plugin/plugin.json" fi jq -r --arg n "$name" '.plugins[]|select(.name==$n)|.version' "$root/.claude-plugin/marketplace.json" - jq -r --arg n "$name" '.plugins[]|select(.name==$n)|.version' "$root/.github/plugin/marketplace.json" } expect_all() { @@ -70,7 +66,7 @@ expect_all() { got=$(versions_of "$root" "$name") uniq=$(printf '%s\n' "$got" | sort -u | tr '\n' ' ') if [ "$uniq" = "$want " ]; then ok "$desc"; else - ko "$desc — expected all four at '$want', got: $uniq"; fi + ko "$desc — expected every manifest at '$want', got: $uniq"; fi } WORK=$(mktemp -d) @@ -79,9 +75,9 @@ fresh() { local d; d=$(mktemp -d "$WORK/case-XXXXXX"); make_repo "$d"; printf '% echo "bump-plugin-version.sh self-test" -# --- all four manifests move together --- +# --- every manifest moves together --- d=$(fresh); (cd "$d" && "$BUMP" alpha patch >/dev/null) -expect_all "patch bumps all four manifests" "$d" alpha "1.2.4" +expect_all "patch bumps every manifest" "$d" alpha "1.2.4" d=$(fresh); (cd "$d" && "$BUMP" alpha minor >/dev/null) expect_all "minor resets patch" "$d" alpha "1.3.0" @@ -146,7 +142,7 @@ if (cd "$d" && "$BUMP" --changed-since origin/nope) >/dev/null 2>&1; then ko "unresolvable base should fail"; else ok "unresolvable base fails closed"; fi # Exercise the real updater with failed Git observations. Enumeration and all -# change queries must finish before any of the four manifests are written. +# change queries must finish before any manifest is written. REAL_GIT=$(command -v git) export REAL_GIT mkdir -p "$WORK/git-fault" @@ -161,7 +157,7 @@ case $VERSION_GIT_FAULT in fi ;; diff-empty|diff-partial) if [[ $1 == diff && ${!#} == plugins/beta/ ]]; then - [[ $VERSION_GIT_FAULT != diff-partial ]] || printf 'plugins/beta/plugin.json\n' + [[ $VERSION_GIT_FAULT != diff-partial ]] || printf 'plugins/beta/.claude-plugin/plugin.json\n' printf 'injected plugin change query failure\n' >&2 exit 72 fi ;; @@ -199,17 +195,17 @@ done # Malformed late inputs must not leave an earlier manifest (or plugin) bumped. for corruption in missing duplicate identity parity malformed symlink; do d=$(fresh) - f="$d/.github/plugin/marketplace.json" + f="$d/.claude-plugin/marketplace.json" case "$corruption" in missing) jq '.plugins |= map(select(.name != "alpha"))' "$f" > "$d/t"; mv "$d/t" "$f" ;; duplicate) jq '.plugins += [.plugins[0]]' "$f" > "$d/t"; mv "$d/t" "$f" ;; - identity) jq '.name="beta"' "$d/plugins/alpha/plugin.json" > "$d/t"; mv "$d/t" "$d/plugins/alpha/plugin.json" ;; + identity) jq '.name="beta"' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/t"; mv "$d/t" "$d/plugins/alpha/.claude-plugin/plugin.json" ;; parity) jq '.plugins[0].version="1.2.2"' "$f" > "$d/t"; mv "$d/t" "$f" ;; malformed) printf '{invalid\n' > "$f" ;; symlink) - cp "$d/plugins/alpha/plugin.json" "$WORK/outside-manifest" - rm "$d/plugins/alpha/plugin.json" - ln -s "$WORK/outside-manifest" "$d/plugins/alpha/plugin.json" + cp "$d/plugins/alpha/.claude-plugin/plugin.json" "$WORK/outside-manifest" + rm "$d/plugins/alpha/.claude-plugin/plugin.json" + ln -s "$WORK/outside-manifest" "$d/plugins/alpha/.claude-plugin/plugin.json" cp "$WORK/outside-manifest" "$WORK/outside-before" ;; esac git -C "$d" diff > "$WORK/before" @@ -218,13 +214,13 @@ for corruption in missing duplicate identity parity malformed symlink; do outside_ok=true if [ "$corruption" = symlink ]; then cmp -s "$WORK/outside-before" "$WORK/outside-manifest" || outside_ok=false; fi if "$outside_ok" && [ "$rc" -ne 0 ] && cmp -s "$WORK/before" "$WORK/after" && [ -z "$(git -C "$d" ls-files --others --exclude-standard)" ]; then - ok "$corruption input leaves all four manifests unchanged" - else ko "$corruption input leaves all four manifests unchanged (rc=$rc)"; fi + ok "$corruption input leaves every manifest unchanged" + else ko "$corruption input leaves every manifest unchanged (rc=$rc)"; fi done d=$(fresh) make_plugin "$d" alpha 1.2.3 "edited alpha" make_plugin "$d" beta 1.2.3 "edited beta" -printf '{invalid\n' > "$d/plugins/beta/plugin.json" +printf '{invalid\n' > "$d/plugins/beta/.claude-plugin/plugin.json" git -C "$d" add plugins/alpha plugins/beta git -C "$d" commit --quiet -m content (cd "$d" && "$BUMP" --changed-since HEAD^ > "$WORK/out" 2>&1); rc=$? @@ -237,27 +233,27 @@ else ko "a bad later plugin prevents every manifest write (rc=$rc)"; fi with_codex() { local root=$1 mkdir -p "$root/plugins/alpha/.codex-plugin" - jq '. + {skills: "./skills/"}' "$root/plugins/alpha/plugin.json" > "$root/plugins/alpha/.codex-plugin/plugin.json" + jq '. + {skills: "./skills/"}' "$root/plugins/alpha/.claude-plugin/plugin.json" > "$root/plugins/alpha/.codex-plugin/plugin.json" } d=$(fresh); with_codex "$d"; (cd "$d" && "$BUMP" alpha minor >/dev/null) -expect_all "a Codex manifest is bumped with the other four" "$d" alpha "1.3.0" +expect_all "a Codex manifest is bumped with the others" "$d" alpha "1.3.0" if jq -e '.skills == "./skills/"' "$d/plugins/alpha/.codex-plugin/plugin.json" >/dev/null; then ok "the Codex manifest keeps its own fields" else ko "the Codex manifest keeps its own fields"; fi d=$(fresh); with_codex "$d" jq '.version = "9.9.9"' "$d/plugins/alpha/.codex-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.codex-plugin/plugin.json" -find "$d/plugins" "$d/.claude-plugin" "$d/.github" -type f -exec cksum {} + | sort > "$WORK/before" +find "$d/plugins" "$d/.claude-plugin" -type f -exec cksum {} + | sort > "$WORK/before" (cd "$d" && "$BUMP" alpha patch > "$WORK/out" 2>&1); rc=$? -find "$d/plugins" "$d/.claude-plugin" "$d/.github" -type f -exec cksum {} + | sort > "$WORK/after" +find "$d/plugins" "$d/.claude-plugin" -type f -exec cksum {} + | sort > "$WORK/after" if [ "$rc" -ne 0 ] && cmp -s "$WORK/before" "$WORK/after"; then ok "Codex manifest version drift is refused before any write" else ko "Codex manifest version drift is refused before any write (rc=$rc)"; fi d=$(fresh); mkdir -p "$WORK/elsewhere-$$"; ln -s "$WORK/elsewhere-$$" "$d/plugins/alpha/.codex-plugin" -jq . "$d/plugins/alpha/plugin.json" > "$WORK/elsewhere-$$/plugin.json" +jq . "$d/plugins/alpha/.claude-plugin/plugin.json" > "$WORK/elsewhere-$$/plugin.json" (cd "$d" && "$BUMP" alpha patch > "$WORK/out" 2>&1); rc=$? -if [ "$rc" -ne 0 ] && [ "$(jq -r .version "$d/plugins/alpha/plugin.json")" = 1.2.3 ]; then +if [ "$rc" -ne 0 ] && [ "$(jq -r .version "$d/plugins/alpha/.claude-plugin/plugin.json")" = 1.2.3 ]; then ok "a symlinked Codex manifest folder is refused" else ko "a symlinked Codex manifest folder is refused (rc=$rc)"; fi echo "-----------------------------------------" diff --git a/scripts/check-plugin-version-bump.sh b/scripts/check-plugin-version-bump.sh index f40424c..d40a2a7 100755 --- a/scripts/check-plugin-version-bump.sh +++ b/scripts/check-plugin-version-bump.sh @@ -26,8 +26,8 @@ plugin_version_history || exit 1 BASE_REF="${1:-${BASE_REF:-origin/main}}" HEAD_REF="${2:-${HEAD_REF:-HEAD}}" -# The strict Claude manifest is the version source of truth. validate-manifests.sh already -# enforces that the portable plugin.json and both marketplace manifests carry the same +# The plugin manifest is the version source of truth. validate-manifests.sh already +# enforces that it and the marketplace manifest (and a Codex manifest, when present) carry the same # version, so checking one here cannot disagree with the others. MANIFEST_REL=".claude-plugin/plugin.json" @@ -91,11 +91,9 @@ while IFS= read -r -d '' plugin_dir; do if [ "$base_version" = "$head_version" ]; then echo "::error::$name: shipped content changed but the version is still $head_version." echo "::error::Consumers cache by version, so this change would never reach them." - echo "::error::Bump the version in all four manifests, then re-run ./scripts/validate-manifests.sh:" - echo "::error:: $plugin_dir/plugin.json" + echo "::error::Bump the version with ./scripts/bump-plugin-version.sh, which moves it in each manifest:" echo "::error:: $plugin_dir/$MANIFEST_REL" echo "::error:: .claude-plugin/marketplace.json (the '$name' entry)" - echo "::error:: .github/plugin/marketplace.json (the '$name' entry)" echo "::error::Changed files in $name:" printf '%s\n' "$changed" | sed 's/^/::error:: /' violations=$((violations + 1)) diff --git a/scripts/check-plugin-version-bump.test.sh b/scripts/check-plugin-version-bump.test.sh index c6ef0be..17678dc 100755 --- a/scripts/check-plugin-version-bump.test.sh +++ b/scripts/check-plugin-version-bump.test.sh @@ -17,23 +17,20 @@ GUARD="$SCRIPT_DIR/check-plugin-version-bump.sh" pass=0 fail=0 -# Write plugins/ with the strict Claude manifest, the portable manifest, and a skill. +# Write plugins/ with its .claude-plugin/plugin.json manifest and a skill. make_plugin() { local root="$1" name="$2" version="$3" body="${4:-original body}" mkdir -p "$root/plugins/$name/.claude-plugin" "$root/plugins/$name/skills/example-skill" local pj pj=$(printf '{"name":"%s","description":"%s plugin","version":"%s"}' "$name" "$name" "$version") - printf '%s\n' "$pj" > "$root/plugins/$name/plugin.json" printf '%s\n' "$pj" > "$root/plugins/$name/.claude-plugin/plugin.json" printf -- '---\nname: example-skill\ndescription: Example\n---\n\n%s\n' "$body" \ > "$root/plugins/$name/skills/example-skill/SKILL.md" } set_version() { - local root="$1" name="$2" version="$3" f - for f in "$root/plugins/$name/plugin.json" "$root/plugins/$name/.claude-plugin/plugin.json"; do - jq --arg v "$version" '.version = $v' "$f" > "$f.tmp" && mv "$f.tmp" "$f" - done + local root="$1" name="$2" version="$3" f="$1/plugins/$2/.claude-plugin/plugin.json" + jq --arg v "$version" '.version = $v' "$f" > "$f.tmp" && mv "$f.tmp" "$f" } # A repo whose main branch holds two plugins at 1.0.0, with a feature branch checked out. @@ -135,8 +132,8 @@ check_fail "failure names the changed file" \ d=$(fresh) make_plugin "$d" alpha "1.0.0" "edited body" commit_all "$d" "content, no bump" -check_fail "failure names the marketplace manifests to bump" \ - ".github/plugin/marketplace.json" "$d" +check_fail "failure names the marketplace manifest to bump" \ + ".claude-plugin/marketplace.json (the 'alpha' entry)" "$d" # Catching only the first plugin would let a second stale plugin ship in the same change. d=$(fresh) diff --git a/scripts/generated-write-safety.test.sh b/scripts/generated-write-safety.test.sh index a1f662a..f28b3cc 100644 --- a/scripts/generated-write-safety.test.sh +++ b/scripts/generated-write-safety.test.sh @@ -89,14 +89,12 @@ rc=0; (cd "$root" && PATH="$root/bin:$PATH" bash "$digest") > "$work/out" 2>&1 | label='failed resource commit reports failure'; check test "$rc" -ne 0 label='failed resource commit restores the whole batch'; check diff -rq "$work/before-digests" "$root/plugins" -# Prepare a plugin with all four version manifests in parity, without a Git history. +# Prepare a plugin whose plugin and marketplace manifests agree, without a Git history. version_fixture() { root=$(mktemp -d "$work/version.XXXXXX") - mkdir -p "$root/plugins/alpha/.claude-plugin" "$root/.github/plugin" "$root/.claude-plugin" - printf '{"name":"alpha","version":"1.2.3"}\n' > "$root/plugins/alpha/plugin.json" - cp "$root/plugins/alpha/plugin.json" "$root/plugins/alpha/.claude-plugin/plugin.json" - printf '{"plugins":[{"name":"alpha","version":"1.2.3","source":"./plugins/alpha"}]}\n' > "$root/.github/plugin/marketplace.json" - cp "$root/.github/plugin/marketplace.json" "$root/.claude-plugin/marketplace.json" + mkdir -p "$root/plugins/alpha/.claude-plugin" "$root/.claude-plugin" + printf '{"name":"alpha","version":"1.2.3"}\n' > "$root/plugins/alpha/.claude-plugin/plugin.json" + printf '{"plugins":[{"name":"alpha","version":"1.2.3","source":"./plugins/alpha"}]}\n' > "$root/.claude-plugin/marketplace.json" } version_fixture cp -R "$root" "$work/before-versions" @@ -104,8 +102,7 @@ faults rc=0; (cd "$root" && PATH="$root/bin:$PATH" bash "$bump" alpha patch) > "$work/out" 2>&1 || rc=$? label='failed version commit reports failure'; check test "$rc" -ne 0 label='failed version commit restores every manifest'; check diff -rq "$work/before-versions/plugins" "$root/plugins" -label='failed version commit restores both catalogues'; check diff -rq "$work/before-versions/.github" "$root/.github" -label='failed version commit restores strict catalogue'; check diff -rq "$work/before-versions/.claude-plugin" "$root/.claude-plugin" +label='failed version commit restores the catalogue'; check diff -rq "$work/before-versions/.claude-plugin" "$root/.claude-plugin" label='failed version commit removes private staging files'; check test "$(find "$root" -name '*.next.*' -o -name '*.original.*' | wc -l | tr -d ' ')" = 0 # A failed later write must preserve a concurrent edit and its original backup. @@ -114,9 +111,9 @@ mkdir "$root/bin" cat > "$root/bin/mv" <<'STUB' #!/usr/bin/env bash last=${!#} -if [[ ${ATOMIC_DESTINATION:-} == plugins/alpha/.claude-plugin/plugin.json && $last == plugin.json && $* == *.next.* && ! -e "$FAULT_ROOT/once" ]]; then - printf '{"name":"alpha","version":"1.2.4","description":"concurrent edit"}\n' > "$FAULT_ROOT/plugins/alpha/plugin.json" - cp "$FAULT_ROOT/plugins/alpha/plugin.json" "$FAULT_ROOT/concurrent-evidence.json" +if [[ ${ATOMIC_DESTINATION:-} == .claude-plugin/marketplace.json && $last == marketplace.json && $* == *.next.* && ! -e "$FAULT_ROOT/once" ]]; then + printf '{"name":"alpha","version":"1.2.4","description":"concurrent edit"}\n' > "$FAULT_ROOT/plugins/alpha/.claude-plugin/plugin.json" + cp "$FAULT_ROOT/plugins/alpha/.claude-plugin/plugin.json" "$FAULT_ROOT/concurrent-evidence.json" touch "$FAULT_ROOT/once" exit 1 fi @@ -126,7 +123,7 @@ chmod +x "$root/bin/mv" rc=0 (cd "$root" && PATH="$root/bin:$PATH" REAL_MV="$real_mv" FAULT_ROOT="$root" bash "$bump" alpha patch) > "$work/out" 2>&1 || rc=$? label='conflicting rollback reports failure'; check test "$rc" -ne 0 -label='conflicting rollback preserves concurrent bytes'; check cmp -s "$root/concurrent-evidence.json" "$root/plugins/alpha/plugin.json" +label='conflicting rollback preserves concurrent bytes'; check cmp -s "$root/concurrent-evidence.json" "$root/plugins/alpha/.claude-plugin/plugin.json" label='conflicting rollback retains the original for recovery'; check test "$(find "$root" -name 'plugin.json.original.*' | wc -l | tr -d ' ')" = 1 label='conflicting rollback explains operator recovery'; check grep -Fq 'Recovery required' "$work/out" @@ -135,12 +132,12 @@ label='conflicting rollback explains operator recovery'; check grep -Fq 'Recover version_fixture mkdir "$root/bin" printf '{"name":"alpha","version":"1.2.4","description":"second writer"}\n' > "$root/second-source" -cp "$root/plugins/alpha/plugin.json" "$root/second-original" -printf '%s\0%s\0%s\0' plugins/alpha/plugin.json "$root/second-source" "$root/second-original" > "$root/second-plan" +cp "$root/plugins/alpha/.claude-plugin/plugin.json" "$root/second-original" +printf '%s\0%s\0%s\0' plugins/alpha/.claude-plugin/plugin.json "$root/second-source" "$root/second-original" > "$root/second-plan" cat > "$root/bin/mv" <<'STUB' #!/usr/bin/env bash last=${!#} -if [[ ${ATOMIC_DESTINATION:-} == plugins/alpha/.claude-plugin/plugin.json && $last == plugin.json && $* == *.next.* && ! -e "$FAULT_ROOT/failed-second" ]]; then +if [[ ${ATOMIC_DESTINATION:-} == .claude-plugin/marketplace.json && $last == marketplace.json && $* == *.next.* && ! -e "$FAULT_ROOT/failed-second" ]]; then touch "$FAULT_ROOT/failed-second" exit 1 fi @@ -149,7 +146,7 @@ STUB cat > "$root/bin/cmp" <<'STUB' #!/usr/bin/env bash rc=0; "$REAL_CMP" "$@" || rc=$? -if [[ $rc == 0 && ${ATOMIC_DESTINATION:-} == plugins/alpha/plugin.json && ${2:-} == plugin.json && -e "$FAULT_ROOT/failed-second" && ! -e "$FAULT_ROOT/probed" ]]; then +if [[ $rc == 0 && ${ATOMIC_DESTINATION:-} == plugins/alpha/.claude-plugin/plugin.json && ${2:-} == plugin.json && -e "$FAULT_ROOT/failed-second" && ! -e "$FAULT_ROOT/probed" ]]; then touch "$FAULT_ROOT/probed" child_rc=0 bash -c 'cd "$FAULT_ROOT"; . "$ATOMIC_LIB"; atomic_write_batch "$FAULT_ROOT/second-plan"' > "$FAULT_ROOT/second-output" 2>&1 || child_rc=$? @@ -167,12 +164,10 @@ label='ordinary failed batch releases its own lock'; check test ! -e "$root/.age version_fixture mkdir -p "$root/plugins/beta/.claude-plugin" "$root/bin" -jq '.name="beta"' "$root/plugins/alpha/plugin.json" > "$root/plugins/beta/plugin.json" -cp "$root/plugins/beta/plugin.json" "$root/plugins/beta/.claude-plugin/plugin.json" -for manifest in .github/plugin/marketplace.json .claude-plugin/marketplace.json; do - jq '.plugins += [{name:"beta",version:"1.2.3",source:"./plugins/beta"}]' "$root/$manifest" > "$work/marketplace" - cp "$work/marketplace" "$root/$manifest" -done +jq '.name="beta"' "$root/plugins/alpha/.claude-plugin/plugin.json" > "$root/plugins/beta/.claude-plugin/plugin.json" +manifest=.claude-plugin/marketplace.json +jq '.plugins += [{name:"beta",version:"1.2.3",source:"./plugins/beta"}]' "$root/$manifest" > "$work/marketplace" +cp "$work/marketplace" "$root/$manifest" cat > "$root/bin/go" <<'STUB' #!/usr/bin/env bash if [[ ${NESTED_WRITER:-} != yes && $1 == build ]]; then @@ -185,25 +180,24 @@ real_go=$(command -v go) rc=0 (cd "$root" && PATH="$root/bin:$PATH" RACE_ROOT="$root" BUMP_TOOL="$bump" REAL_GO="$real_go" bash "$bump" alpha patch) > "$work/out" 2>&1 || rc=$? label='a stale writer plan refuses before erasing a completed bump'; check test "$rc" -ne 0 -for manifest in .github/plugin/marketplace.json .claude-plugin/marketplace.json; do - label="completed beta bump survives in $manifest"; check jq -e '.plugins[] | select(.name=="beta") | .version=="1.2.4"' "$root/$manifest" -done -label='stale alpha batch does not publish its first destination'; check jq -e '.version=="1.2.3"' "$root/plugins/alpha/plugin.json" +manifest=.claude-plugin/marketplace.json +label="completed beta bump survives in $manifest"; check jq -e '.plugins[] | select(.name=="beta") | .version=="1.2.4"' "$root/$manifest" +label='stale alpha batch does not publish its first destination'; check jq -e '.version=="1.2.3"' "$root/plugins/alpha/.claude-plugin/plugin.json" # A changed later target refuses the whole plan before its first replacement. version_fixture -cp "$root/plugins/alpha/plugin.json" "$root/first-observed" -cp "$root/plugins/alpha/.claude-plugin/plugin.json" "$root/second-observed" +cp "$root/plugins/alpha/.claude-plugin/plugin.json" "$root/first-observed" +cp "$root/.claude-plugin/marketplace.json" "$root/second-observed" printf 'replacement\n' > "$root/planned-source" -printf '%s\0%s\0%s\0' plugins/alpha/plugin.json "$root/planned-source" "$root/first-observed" \ - plugins/alpha/.claude-plugin/plugin.json "$root/planned-source" "$root/second-observed" > "$root/stale-plan" -printf 'concurrent second target\n' > "$root/plugins/alpha/.claude-plugin/plugin.json" -cp "$root/plugins/alpha/.claude-plugin/plugin.json" "$root/concurrent-second" +printf '%s\0%s\0%s\0' plugins/alpha/.claude-plugin/plugin.json "$root/planned-source" "$root/first-observed" \ + .claude-plugin/marketplace.json "$root/planned-source" "$root/second-observed" > "$root/stale-plan" +printf 'concurrent second target\n' > "$root/.claude-plugin/marketplace.json" +cp "$root/.claude-plugin/marketplace.json" "$root/concurrent-second" rc=0 (cd "$root" && bash -c '. "$1"; atomic_write_batch stale-plan' _ "$plugins/scripts/atomic-write.lib.sh") > "$work/out" 2>&1 || rc=$? label='stale later destination refuses publication'; check test "$rc" -ne 0 -label='stale later destination leaves the first target unchanged'; check cmp -s "$root/first-observed" "$root/plugins/alpha/plugin.json" -label='stale later destination preserves the foreign update'; check cmp -s "$root/concurrent-second" "$root/plugins/alpha/.claude-plugin/plugin.json" +label='stale later destination leaves the first target unchanged'; check cmp -s "$root/first-observed" "$root/plugins/alpha/.claude-plugin/plugin.json" +label='stale later destination preserves the foreign update'; check cmp -s "$root/concurrent-second" "$root/.claude-plugin/marketplace.json" # Observed absence has the same protection as an existing file's original bytes. version_fixture @@ -225,10 +219,10 @@ label='an uncontended new file contains the planned bytes'; check cmp -s "$root/ version_fixture mkdir "$root/.agent-plugin-write.lock" -cp "$root/plugins/alpha/plugin.json" "$work/locked-before" +cp "$root/plugins/alpha/.claude-plugin/plugin.json" "$work/locked-before" rc=0; (cd "$root" && bash "$bump" alpha patch) > "$work/out" 2>&1 || rc=$? label='a pre-existing writer lock refuses publication'; check test "$rc" -ne 0 -label='a pre-existing writer lock preserves destination bytes'; check cmp -s "$work/locked-before" "$root/plugins/alpha/plugin.json" +label='a pre-existing writer lock preserves destination bytes'; check cmp -s "$work/locked-before" "$root/plugins/alpha/.claude-plugin/plugin.json" label='a failed lock acquisition cannot remove another writer lock'; check test -d "$root/.agent-plugin-write.lock" # Relative staging names belong to the caller, never to a destination parent. @@ -236,12 +230,12 @@ version_fixture mkdir -p "$root/staging" "$root/plugins/alpha/staging" printf 'caller bytes\n' > "$root/staging/source" printf 'wrong parent bytes\n' > "$root/plugins/alpha/staging/source" -cp "$root/plugins/alpha/plugin.json" "$root/staging/original" -printf '%s\0%s\0%s\0' plugins/alpha/plugin.json staging/source staging/original > "$root/relative-plan" +cp "$root/plugins/alpha/.claude-plugin/plugin.json" "$root/staging/original" +printf '%s\0%s\0%s\0' plugins/alpha/.claude-plugin/plugin.json staging/source staging/original > "$root/relative-plan" rc=0 (cd "$root" && bash -c '. "$1"; atomic_write_batch relative-plan' _ "$plugins/scripts/atomic-write.lib.sh") > "$work/out" 2>&1 || rc=$? label='relative staging source stays bound to caller root'; check test "$rc" -eq 0 -label='relative staging cannot publish a destination-parent impostor'; check cmp "$root/staging/source" "$root/plugins/alpha/plugin.json" +label='relative staging cannot publish a destination-parent impostor'; check cmp "$root/staging/source" "$root/plugins/alpha/.claude-plugin/plugin.json" # Cleanup must retain recovery files once the caller checkout path has moved. version_fixture @@ -249,8 +243,8 @@ mkdir "$root/bin" outside=$(mktemp -d "$work/moved-outside.XXXXXX") cp -R "$root/." "$outside/" printf 'replacement\n' > "$work/moved-source" -cp "$root/plugins/alpha/plugin.json" "$work/moved-original" -printf '%s\0%s\0%s\0' plugins/alpha/plugin.json "$work/moved-source" "$work/moved-original" > "$root/moved-plan" +cp "$root/plugins/alpha/.claude-plugin/plugin.json" "$work/moved-original" +printf '%s\0%s\0%s\0' plugins/alpha/.claude-plugin/plugin.json "$work/moved-source" "$work/moved-original" > "$root/moved-plan" cat > "$root/bin/cp" <<'STUB' #!/usr/bin/env bash last=${!#} @@ -265,22 +259,20 @@ chmod +x "$root/bin/cp" rc=0 (cd "$root" && PATH="$root/bin:$PATH" RACE_ROOT="$root" RACE_OUTSIDE="$outside" RACE_FLAG="$work/moved-flag" REAL_CP="$(command -v cp)" REAL_MV="$(command -v mv)" bash -c '. "$1"; atomic_write_batch moved-plan' _ "$plugins/scripts/atomic-write.lib.sh") > "$work/out" 2>&1 || rc=$? label='moved checkout refuses publication'; check test "$rc" -ne 0 -label='moved checkout leaves external destination untouched'; check cmp "$outside/plugins/alpha/plugin.json" "$root.owned/plugins/alpha/plugin.json" +label='moved checkout leaves external destination untouched'; check cmp "$outside/plugins/alpha/.claude-plugin/plugin.json" "$root.owned/plugins/alpha/.claude-plugin/plugin.json" label='moved checkout retains its original for recovery'; check test "$(find "$root.owned" -name '*.original.*' | wc -l | tr -d ' ')" -eq 1 version_fixture git -C "$root" init -q git -C "$root" config user.name Test; git -C "$root" config user.email test@example.invalid -git -C "$root" -c commit.gpgsign=false add plugins .github/plugin/marketplace.json .claude-plugin/marketplace.json +git -C "$root" -c commit.gpgsign=false add plugins .claude-plugin/marketplace.json git -C "$root" -c commit.gpgsign=false commit -qm base base=$(git -C "$root" rev-parse HEAD) mkdir -p "$root/plugins/beta/.claude-plugin" -printf '{"name":"beta","version":"1.0.0"}\n' > "$root/plugins/beta/plugin.json" -cp "$root/plugins/beta/plugin.json" "$root/plugins/beta/.claude-plugin/plugin.json" -for f in .github/plugin/marketplace.json .claude-plugin/marketplace.json; do - jq '.plugins += [{name:"beta",version:"1.0.0",source:"./plugins/beta"}]' "$root/$f" > "$work/new"; cp "$work/new" "$root/$f" -done -git -C "$root" add plugins/beta .github/plugin/marketplace.json .claude-plugin/marketplace.json +printf '{"name":"beta","version":"1.0.0"}\n' > "$root/plugins/beta/.claude-plugin/plugin.json" +f=.claude-plugin/marketplace.json +jq '.plugins += [{name:"beta",version:"1.0.0",source:"./plugins/beta"}]' "$root/$f" > "$work/new"; cp "$work/new" "$root/$f" +git -C "$root" add plugins/beta .claude-plugin/marketplace.json git -C "$root" -c commit.gpgsign=false commit -qm 'feat: new plugin' rc=0; (cd "$root" && bash "$bump" --changed-since "$base") > "$work/out" 2>&1 || rc=$? label='changed-since accepts a newly introduced plugin'; check test "$rc" -eq 0 diff --git a/scripts/guard-bundled-skill-edits.sh b/scripts/guard-bundled-skill-edits.sh index 4299ecf..4e683fc 100755 --- a/scripts/guard-bundled-skill-edits.sh +++ b/scripts/guard-bundled-skill-edits.sh @@ -24,7 +24,7 @@ # - Adding a wholly NEW skill directory. It does not exist at the base ref, so # there is no upstream copy to diverge from yet; `gh skill install` followed by # a commit stays a one-step operation. -# - Everything authored here: manifests, plugin.json, agents/, docs, scripts. +# - Everything authored here: manifests, .claude-plugin/plugin.json, agents/, docs, scripts. # # WHAT IT CANNOT CHECK # Whether the bundled bytes still match the upstream. There is no lockfile, and diff --git a/scripts/guard-bundled-skill-edits.test.sh b/scripts/guard-bundled-skill-edits.test.sh index 0ba472c..fa1bd2a 100755 --- a/scripts/guard-bundled-skill-edits.test.sh +++ b/scripts/guard-bundled-skill-edits.test.sh @@ -55,7 +55,7 @@ git -C "$FIXTURE" config user.name test git -C "$FIXTURE" config commit.gpgsign false mkdir -p "$FIXTURE/plugins/github/skills/github-issues/references" -mkdir -p "$FIXTURE/plugins/agentic-engineering/agents" +mkdir -p "$FIXTURE/plugins/agentic-engineering/agents" "$FIXTURE/plugins/github/.claude-plugin" cat > "$FIXTURE/plugins/github/skills/github-issues/SKILL.md" <<'SKILL' --- name: github-issues @@ -67,7 +67,7 @@ metadata: body SKILL echo 'docs' > "$FIXTURE/plugins/github/skills/github-issues/references/milestones.md" -echo '{}' > "$FIXTURE/plugins/github/plugin.json" +echo '{}' > "$FIXTURE/plugins/github/.claude-plugin/plugin.json" echo 'x' > "$FIXTURE/plugins/agentic-engineering/agents/agentic-engineer.agent.md" git -C "$FIXTURE" add -A git -C "$FIXTURE" commit -qm base @@ -100,7 +100,7 @@ run 'docs/adr/0001.md README.md' expect 0 'no bundled skill tree touched' 'a change touching no skill tree passes' -run 'plugins/github/plugin.json +run 'plugins/github/.claude-plugin/plugin.json plugins/agentic-engineering/agents/agentic-engineer.agent.md' expect 0 'no bundled skill tree touched' 'authored plugin files are not mistaken for skill content' diff --git a/scripts/guard-gh-json-fields.test.sh b/scripts/guard-gh-json-fields.test.sh index 9e29dcb..cb50196 100755 --- a/scripts/guard-gh-json-fields.test.sh +++ b/scripts/guard-gh-json-fields.test.sh @@ -34,7 +34,7 @@ expect() { # and every case isolates the one surface under test. fixture() { local dir="${work}/$1" - mkdir -p "${dir}/plugins/p/agents" + mkdir -p "${dir}/plugins/p/agents" "${dir}/plugins/p/.claude-plugin" printf '%s\n' '`gh pr view --json state,mergedAt`' > "${dir}/plugins/p/agents/baseline.md" printf '%s' "${dir}" } @@ -116,16 +116,16 @@ done # JSON surfaces are decoded: a \u-escaped letter is still that letter, so an escaped field name is caught. dir="$(fixture bad-json-escaped-name)" -printf '{"prompt":"gh pr view --json state,\x5cu006derged,mergedAt"}\n' > "${dir}/plugins/p/plugin.json" +printf '{"prompt":"gh pr view --json state,\x5cu006derged,mergedAt"}\n' > "${dir}/plugins/p/.claude-plugin/plugin.json" expect 1 "JSON with an escaped field name" "${dir}" dir="$(fixture bad-json-escaped-space)" -printf '{"prompt":"gh pr view --json\x5cu0020state,merged,closed"}\n' > "${dir}/plugins/p/plugin.json" +printf '{"prompt":"gh pr view --json\x5cu0020state,merged,closed"}\n' > "${dir}/plugins/p/.claude-plugin/plugin.json" expect 1 "JSON with an escaped separator" "${dir}" # A command stored as an object KEY is scanned too. dir="$(fixture bad-json-key)" -printf '%s\n' '{"gh pr view --json state,merged":"example to run"}' > "${dir}/plugins/p/plugin.json" +printf '%s\n' '{"gh pr view --json state,merged":"example to run"}' > "${dir}/plugins/p/.claude-plugin/plugin.json" expect 1 "JSON with the request as an object key" "${dir}" # An argv array is one command, so `--json` and its next element are read together. @@ -139,21 +139,21 @@ expect 0 "JSON argv array with valid fields" "${dir}" # Any OTHER array keeps its elements apart: two notes do not form a command. dir="$(fixture good-json-notes-array)" -printf '%s\n' '{"notes":["The option is --json","merged is unavailable"]}' > "${dir}/plugins/p/plugin.json" +printf '%s\n' '{"notes":["The option is --json","merged is unavailable"]}' > "${dir}/plugins/p/.claude-plugin/plugin.json" expect 0 "a non-argv string array is not joined" "${dir}" # A decoded NUL anywhere in the file must not make grep treat it as binary and print nothing. dir="$(fixture bad-json-nul)" -printf '{"note":"a\x5cu0000b","prompt":"gh pr view --json state,merged"}\n' > "${dir}/plugins/p/plugin.json" +printf '{"note":"a\x5cu0000b","prompt":"gh pr view --json state,merged"}\n' > "${dir}/plugins/p/.claude-plugin/plugin.json" expect 1 "JSON containing a NUL still has its request scanned" "${dir}" # Two unrelated values must not join into `--json merged`. dir="$(fixture good-json-boundary)" -printf '%s\n' '{"label":"CLI option --json","description":"merged is not a valid field"}' > "${dir}/plugins/p/plugin.json" +printf '%s\n' '{"label":"CLI option --json","description":"merged is not a valid field"}' > "${dir}/plugins/p/.claude-plugin/plugin.json" expect 0 "JSON values stay separate" "${dir}" dir="$(fixture good-json-prose-comma)" -printf '%s\n' '{"prompt":"Run gh pr view --json state, merged PRs need no polling."}' > "${dir}/plugins/p/plugin.json" +printf '%s\n' '{"prompt":"Run gh pr view --json state, merged PRs need no polling."}' > "${dir}/plugins/p/.claude-plugin/plugin.json" expect 0 "JSON comma-then-space is prose" "${dir}" # A skill file deep in the tree is scanned too — synced skills are the likeliest source. @@ -543,7 +543,7 @@ if [ "$(id -u)" -ne 0 ]; then fi dir="$(fixture unknown-bad-json)" -printf '%s\n' '{"prompt": "gh pr view --json state,merged"' > "${dir}/plugins/p/plugin.json" +printf '%s\n' '{"prompt": "gh pr view --json state,merged"' > "${dir}/plugins/p/.claude-plugin/plugin.json" expect 2 "unparseable JSON is UNKNOWN, not clean" "${dir}" mkdir -p "${work}/unknown-no-plugins" diff --git a/scripts/mcp-boundaries.test.sh b/scripts/mcp-boundaries.test.sh index d0b1675..115b29e 100644 --- a/scripts/mcp-boundaries.test.sh +++ b/scripts/mcp-boundaries.test.sh @@ -5,15 +5,13 @@ here=${MCP_SOURCE:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)} work=$(mktemp -d) trap 'rm -rf "$work"' EXIT fail=0 -# Build a complete portable package fixture with matching manifests and resource inventory. +# Build a complete package fixture with matching manifests and resource inventory. fixture() { local root=$1 resource=$2 - mkdir -p "$root/.github/plugin" "$root/.claude-plugin" "$root/scripts" "$root/docs" "$root/plugins/alpha/.claude-plugin" "$root/plugins/alpha/skills/example" + mkdir -p "$root/.claude-plugin" "$root/scripts" "$root/docs" "$root/plugins/alpha/.claude-plugin" "$root/plugins/alpha/skills/example" printf '%s\n' '{"name":"fixture","renames":{"old-alpha":"alpha"},"plugins":[{"name":"alpha","description":"Alpha","version":"1.0.0","source":"./plugins/alpha"}]}' > "$root/.claude-plugin/marketplace.json" - cp "$root/.claude-plugin/marketplace.json" "$root/.github/plugin/marketplace.json" printf '%s\n' '{"old-alpha":"alpha"}' > "$root/scripts/marketplace-rename-history.json" - printf '%s\n' '{"name":"alpha","description":"Alpha","version":"1.0.0"}' > "$root/plugins/alpha/plugin.json" - cp "$root/plugins/alpha/plugin.json" "$root/plugins/alpha/.claude-plugin/plugin.json" + printf '%s\n' '{"name":"alpha","description":"Alpha","version":"1.0.0"}' > "$root/plugins/alpha/.claude-plugin/plugin.json" printf '%s\n' '---' 'name: example' 'description: Example.' 'metadata:' ' github-repo: https://github.com/example/fixture-skills' '---' > "$root/plugins/alpha/skills/example/SKILL.md" # shellcheck disable=SC2016 # Backticks are literal Markdown, not shell substitutions. printf '| Plugin | Resources | Description |\n|---|---|---|\n| [`alpha`](plugins/alpha/) | `example`, `%s` | Alpha |\n' "$resource" > "$root/docs/plugins.md" diff --git a/scripts/package-boundaries.test.sh b/scripts/package-boundaries.test.sh index 2918aa7..cddf22d 100644 --- a/scripts/package-boundaries.test.sh +++ b/scripts/package-boundaries.test.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Exercise the actual package gate with complete portable fixtures and declared resource paths. +# Exercise the actual package gate with complete fixtures and declared resource paths. set -euo pipefail here=${PACKAGE_SOURCE:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)} work=$(mktemp -d) @@ -8,11 +8,10 @@ fail=0 # Build matching manifests, a sourced skill, and a complete catalogue. fixture() { local root=$1 - mkdir -p "$root/.github/plugin" "$root/.claude-plugin" "$root/scripts" "$root/docs" "$root/plugins/alpha/.claude-plugin" "$root/plugins/alpha/skills/example" + mkdir -p "$root/.claude-plugin" "$root/scripts" "$root/docs" "$root/plugins/alpha/.claude-plugin" "$root/plugins/alpha/skills/example" printf '%s\n' '{"name":"fixture","renames":{"old-alpha":"alpha"},"plugins":[{"name":"alpha","description":"Alpha","version":"1.0.0","source":"./plugins/alpha"}]}' > "$root/.claude-plugin/marketplace.json" - cp "$root/.claude-plugin/marketplace.json" "$root/.github/plugin/marketplace.json" printf '%s\n' '{"old-alpha":"alpha"}' > "$root/scripts/marketplace-rename-history.json" - printf '%s\n' '{"name":"alpha","description":"Alpha","version":"1.0.0"}' > "$root/plugins/alpha/plugin.json" + printf '%s\n' '{"name":"alpha","description":"Alpha","version":"1.0.0"}' > "$root/plugins/alpha/.claude-plugin/plugin.json" printf '%s\n' '---' 'name: example' 'description: Example.' 'metadata:' ' github-repo: https://github.com/example/fixture-skills' '---' > "$root/plugins/alpha/skills/example/SKILL.md" # shellcheck disable=SC2016 # Literal catalogue markup. printf '| Plugin | Resources | Description |\n|---|---|---|\n| [`alpha`](plugins/alpha/) | `example` | Alpha |\n' > "$root/docs/plugins.md" @@ -28,7 +27,7 @@ gate() { } for scenario in healthy unicode-description marketplace-name-number marketplace-name-blank duplicate-entries numeric-description blank-description numeric-version unstable-version leading-zero-version oversized-version component-number component-blank component-outside component-absolute component-missing component-wrong-kind component-valid-root component-valid-skill component-symlink component-root-symlink component-nested-layout component-root-skill-layout duplicate-marketplace duplicate-plugin duplicate-renames nested-duplicate escaped-duplicate multiple-objects plugin-parent-symlink; do root="$work/$scenario"; fixture "$root" - m="$root/.claude-plugin/marketplace.json"; p="$root/plugins/alpha/plugin.json" + m="$root/.claude-plugin/marketplace.json"; p="$root/plugins/alpha/.claude-plugin/plugin.json" case $scenario in marketplace-name-number) jq '.name=7' "$m" > "$root/new"; mv "$root/new" "$m" ;; marketplace-name-blank) jq '.name=" "' "$m" > "$root/new"; mv "$root/new" "$m" ;; @@ -56,7 +55,6 @@ for scenario in healthy unicode-description marketplace-name-number marketplace- escaped-duplicate) printf '%s\n' '{"name":"other","na\u006de":"alpha","description":"Alpha","version":"1.0.0"}' > "$p" ;; multiple-objects) cat "$m" "$m" > "$root/new"; mv "$root/new" "$m" ;; esac - cp "$m" "$root/.github/plugin/marketplace.json"; cp "$p" "$root/plugins/alpha/.claude-plugin/plugin.json" if [ "$scenario" = plugin-parent-symlink ]; then mv "$root/plugins/alpha" "$root/elsewhere"; ln -s "$root/elsewhere" "$root/plugins/alpha" fi @@ -64,14 +62,14 @@ for scenario in healthy unicode-description marketplace-name-number marketplace- case $scenario in healthy|unicode-description|component-valid-*) expected=pass ;; esac gate "$scenario" "$expected" "$root" done -# Agent declarations select regular files from the canonical portable layout. +# Agent declarations select regular files from the canonical layout. for scenario in valid number missing outside directory empty invalid-frontmatter; do root="$work/agent-$scenario"; fixture "$root" mkdir -p "$root/plugins/alpha/agents" printf '%s\n' '---' 'name: sample' 'description: Example agent.' '---' > "$root/plugins/alpha/agents/sample.agent.md" case $scenario in valid|invalid-frontmatter) value='["./agents/sample.agent.md"]' ;; number) value='[7]' ;; missing) value='["./agents/absent.agent.md"]' ;; outside) value='["../sample.agent.md"]' ;; directory) value='["./agents/"]' ;; empty) value='[]' ;; esac - p="$root/plugins/alpha/plugin.json" - jq --argjson v "$value" '.agents=$v' "$p" > "$root/new"; mv "$root/new" "$p"; cp "$p" "$root/plugins/alpha/.claude-plugin/plugin.json" + p="$root/plugins/alpha/.claude-plugin/plugin.json" + jq --argjson v "$value" '.agents=$v' "$p" > "$root/new"; mv "$root/new" "$p" if [ "$scenario" != empty ]; then # shellcheck disable=SC2016 # Backticks are literal catalogue markup. sed 's/`example` |/`example`, `sample` |/' "$root/docs/plugins.md" > "$root/new"; mv "$root/new" "$root/docs/plugins.md" @@ -93,7 +91,6 @@ for field in name description; do block-oversized-leading-blank block-leading-tab block-leading-tab-content block-small-tab-indent \ block-continued-after-comment; do root="$work/yaml-$field-$scenario"; fixture "$root" - cp "$root/plugins/alpha/plugin.json" "$root/plugins/alpha/.claude-plugin/plugin.json" mkdir -p "$root/plugins/alpha/agents" value='' body='' expected=reject case "$scenario" in diff --git a/scripts/package-discovery.test.sh b/scripts/package-discovery.test.sh index 59d4ffb..17c1c50 100644 --- a/scripts/package-discovery.test.sh +++ b/scripts/package-discovery.test.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Exercise the actual package gate with complete portable fixtures and declared resource paths. +# Exercise the actual package gate with complete fixtures and declared resource paths. set -euo pipefail here=${PACKAGE_SOURCE:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)} work=$(mktemp -d) @@ -8,11 +8,10 @@ fail=0 # Build matching manifests, a sourced skill, and a complete catalogue. fixture() { local root=$1 - mkdir -p "$root/.github/plugin" "$root/.claude-plugin" "$root/scripts" "$root/docs" "$root/plugins/alpha/.claude-plugin" "$root/plugins/alpha/skills/example" + mkdir -p "$root/.claude-plugin" "$root/scripts" "$root/docs" "$root/plugins/alpha/.claude-plugin" "$root/plugins/alpha/skills/example" printf '%s\n' '{"name":"fixture","renames":{"old-alpha":"alpha"},"plugins":[{"name":"alpha","description":"Alpha","version":"1.0.0","source":"./plugins/alpha"}]}' > "$root/.claude-plugin/marketplace.json" - cp "$root/.claude-plugin/marketplace.json" "$root/.github/plugin/marketplace.json" printf '%s\n' '{"old-alpha":"alpha"}' > "$root/scripts/marketplace-rename-history.json" - printf '%s\n' '{"name":"alpha","description":"Alpha","version":"1.0.0"}' > "$root/plugins/alpha/plugin.json" + printf '%s\n' '{"name":"alpha","description":"Alpha","version":"1.0.0"}' > "$root/plugins/alpha/.claude-plugin/plugin.json" printf '%s\n' '---' 'name: example' 'description: Example.' 'metadata:' ' github-repo: https://github.com/example/fixture-skills' '---' > "$root/plugins/alpha/skills/example/SKILL.md" # shellcheck disable=SC2016 # Literal catalogue markup. printf '| Plugin | Resources | Description |\n|---|---|---|\n| [`alpha`](plugins/alpha/) | `example` | Alpha |\n' > "$root/docs/plugins.md" @@ -30,9 +29,9 @@ gate() { else printf 'FAIL %s exit=%s\n' "$name" "$rc"; cat "$root/out"; fail=$((fail+1)); fi } # Default discovery must apply the same packaged-resource fence as explicit paths. -for scenario in healthy linked-skill linked-agent linked-mcp linked-plugin linked-strict-plugin linked-marketplace linked-strict-parent incomplete-skill orphan-plugin description-backslash selected-agent selected-empty mcp-underscore mcp-dot mcp-unicode mcp-space mcp-backtick mcp-pipe; do +for scenario in healthy linked-skill linked-agent linked-mcp linked-plugin linked-marketplace linked-strict-parent incomplete-skill orphan-plugin description-backslash selected-agent selected-empty mcp-underscore mcp-dot mcp-unicode mcp-space mcp-backtick mcp-pipe; do root="$work/discovery-$scenario"; fixture "$root" - p="$root/plugins/alpha/plugin.json"; m="$root/.claude-plugin/marketplace.json" + p="$root/plugins/alpha/.claude-plugin/plugin.json"; m="$root/.claude-plugin/marketplace.json" case $scenario in linked-skill) mv "$root/plugins/alpha/skills/example/SKILL.md" "$root/outside.md"; printf 'body only\n' > "$root/outside.md"; ln -s "$root/outside.md" "$root/plugins/alpha/skills/example/SKILL.md" ;; linked-agent|selected-agent|selected-empty) @@ -64,10 +63,8 @@ for scenario in healthy linked-skill linked-agent linked-mcp linked-plugin linke jq '.description="Use C:\\tools"' "$p" > "$root/new"; mv "$root/new" "$p" jq --slurpfile p "$p" '.plugins[0].description=$p[0].description' "$m" > "$root/new"; mv "$root/new" "$m" ;; esac - cp "$p" "$root/plugins/alpha/.claude-plugin/plugin.json"; cp "$m" "$root/.github/plugin/marketplace.json" case $scenario in linked-plugin) mv "$p" "$root/outside.json"; ln -s "$root/outside.json" "$p" ;; - linked-strict-plugin) path="$root/plugins/alpha/.claude-plugin/plugin.json"; mv "$path" "$root/outside.json"; ln -s "$root/outside.json" "$path" ;; linked-marketplace) mv "$m" "$root/outside.json"; ln -s "$root/outside.json" "$m" ;; linked-strict-parent) path="$root/plugins/alpha/.claude-plugin"; mv "$path" "$root/outside"; ln -s "$root/outside" "$path" ;; esac @@ -77,10 +74,10 @@ for scenario in healthy linked-skill linked-agent linked-mcp linked-plugin linke linked-skill) diagnostic='plugins/alpha/skills/example: skill directory requires its own regular SKILL.md' ;; linked-agent) diagnostic='plugins/alpha/agents/sample.agent.md: agent must be a regular packaged file' ;; linked-mcp) diagnostic='plugins/alpha/.mcp.json: MCP configuration must be a regular packaged file' ;; - linked-plugin|linked-strict-plugin|linked-strict-parent) diagnostic='plugins/alpha: every package requires its own regular canonical manifests' ;; + linked-plugin|linked-strict-parent) diagnostic='plugins/alpha: every package requires its own regular canonical manifest .claude-plugin/plugin.json' ;; linked-marketplace) diagnostic='.claude-plugin/marketplace.json: manifest must be a regular packaged file' ;; incomplete-skill) diagnostic='plugins/alpha/skills/incomplete: skill directory requires its own regular SKILL.md' ;; - orphan-plugin) diagnostic='plugins/ghost: every package requires its own regular canonical manifests' ;; + orphan-plugin) diagnostic='plugins/ghost: every package requires its own regular canonical manifest .claude-plugin/plugin.json' ;; mcp-space|mcp-backtick|mcp-pipe) diagnostic='plugins/alpha/.mcp.json: MCP server names must be unambiguous catalogue tokens' ;; esac gate "$scenario" "$expected" "$root" "$diagnostic" @@ -99,7 +96,6 @@ for scenario in listed ancillary; do fi # shellcheck disable=SC2016 # Literal catalogue markup. printf '| Plugin | Resources | Description |\n|---|---|---|\n| [`alpha`](plugins/alpha/) | `example`, `sample`%s | Alpha |\n' "$extra" > "$root/docs/plugins.md" - cp "$root/plugins/alpha/plugin.json" "$root/plugins/alpha/.claude-plugin/plugin.json" expected=pass; [ "$scenario" != listed ] || expected=reject gate "agent-token-$scenario" "$expected" "$root" "docs/plugins.md Resources for 'alpha' (example invisible.txt sample) differ from on-disk resources (example sample)" done @@ -107,7 +103,6 @@ done real_find=$(command -v find) for kind in packages skills agents desired-state provenance; do root="$work/unterminated-$kind"; fixture "$root" - cp "$root/plugins/alpha/plugin.json" "$root/plugins/alpha/.claude-plugin/plugin.json" mkdir "$root/bin" cat > "$root/bin/find" <<'STUB' #!/usr/bin/env bash diff --git a/scripts/plugin-changelog-boundaries.test.sh b/scripts/plugin-changelog-boundaries.test.sh index 3fda974..3ac3142 100644 --- a/scripts/plugin-changelog-boundaries.test.sh +++ b/scripts/plugin-changelog-boundaries.test.sh @@ -11,8 +11,8 @@ fixture() { git -C "$dir" config user.name Test; git -C "$dir" config user.email test@example.invalid git -C "$dir" config commit.gpgsign false for plugin in alpha beta; do - mkdir -p "$dir/plugins/$plugin/skills/example" - printf '{"version":"1.2.3"}\n' > "$dir/plugins/$plugin/plugin.json" + mkdir -p "$dir/plugins/$plugin/skills/example" "$dir/plugins/$plugin/.claude-plugin" + printf '{"version":"1.2.3"}\n' > "$dir/plugins/$plugin/.claude-plugin/plugin.json" printf '%s\n' '---' 'name: example' 'metadata:' ' github-repo: https://github.com/example/fixture-skills' ' github-ref: refs/tags/v1.0.0' '---' 'Example.' > "$dir/plugins/$plugin/skills/example/SKILL.md" printf '## 1.2.3 — 2026-01-01\n\nOriginal history.\n' > "$dir/plugins/$plugin/CHANGELOG.md" done @@ -20,7 +20,7 @@ fixture() { base=$(git -C "$dir" rev-parse HEAD) printf '\nChanged resource.\n' >> "$dir/plugins/alpha/skills/example/SKILL.md" git -C "$dir" add -- plugins; git -C "$dir" commit -qm sync - printf '{"version":"1.2.4"}\n' > "$dir/plugins/alpha/plugin.json" + printf '{"version":"1.2.4"}\n' > "$dir/plugins/alpha/.claude-plugin/plugin.json" } # Retain expected refusals as observable status assertions, so one gap cannot mask another. expect_refusal() { @@ -39,13 +39,13 @@ for valid_date in 2000-02-29 2024-02-29 2026-04-30; do else printf 'FAIL valid date %s\n' "$valid_date"; failed=$((failed+1)); fi done fixture -printf '{}\n' >> "$dir/plugins/alpha/plugin.json" +printf '{}\n' >> "$dir/plugins/alpha/.claude-plugin/plugin.json" label='multiple working manifest documents'; expect_refusal write "$base" 2026-10-03 fixture -git -C "$dir" show "$base:plugins/alpha/plugin.json" > "$work/manifest" +git -C "$dir" show "$base:plugins/alpha/.claude-plugin/plugin.json" > "$work/manifest" printf '{"version":"1.2.3"}\n' >> "$work/manifest" blob=$(git -C "$dir" hash-object -w "$work/manifest") -git -C "$dir" update-index --cacheinfo 100644 "$blob" plugins/alpha/plugin.json +git -C "$dir" update-index --cacheinfo 100644 "$blob" plugins/alpha/.claude-plugin/plugin.json git -C "$dir" commit -qm malformed-base base=$(git -C "$dir" rev-parse HEAD) label='multiple base manifest documents'; expect_refusal write "$base" 2026-10-03 @@ -81,7 +81,7 @@ base=$(git -C "$dir" rev-parse HEAD~1) label='non-ASCII resource filenames retain their owning skill' if (cd "$dir" && bash "$script" write "$base" 2026-10-03) > "$work/out" 2>&1 && grep -q '\*\*Changed\*\*' "$dir/plugins/alpha/CHANGELOG.md"; then printf 'PASS %s\n' "$label"; else printf 'FAIL %s\n' "$label"; failed=$((failed+1)); fi fixture -printf '{"version":"1.2.4"}\n' > "$dir/plugins/beta/plugin.json" +printf '{"version":"1.2.4"}\n' > "$dir/plugins/beta/.claude-plugin/plugin.json" printf '\nChanged beta.\n' >> "$dir/plugins/beta/skills/example/SKILL.md" git -C "$dir" add -- plugins/beta/skills/example/SKILL.md; git -C "$dir" commit -qm beta cp "$dir/plugins/alpha/CHANGELOG.md" "$work/alpha-before"; cp "$dir/plugins/beta/CHANGELOG.md" "$work/beta-before" @@ -104,7 +104,7 @@ rc=0 label='failed second write removes its newly created first changelog' if [[ $rc -ne 0 && ! -e "$dir/plugins/alpha/CHANGELOG.md" ]] && cmp -s "$work/beta-before" "$dir/plugins/beta/CHANGELOG.md"; then printf 'PASS %s\n' "$label"; else printf 'FAIL %s\n' "$label"; failed=$((failed+1)); fi fixture -git -C "$dir" add -- plugins/alpha/plugin.json; git -C "$dir" commit -qm version +git -C "$dir" add -- plugins/alpha/.claude-plugin/plugin.json; git -C "$dir" commit -qm version original=$(git -C "$dir" rev-parse HEAD) printf '## 1.2.4 — 2026-10-03\n' > "$dir/plugins/alpha/CHANGELOG.md" git -C "$dir" add -- plugins/alpha/CHANGELOG.md; git -C "$dir" commit -qm substitute-notes diff --git a/scripts/plugin-changelog-release-boundaries.test.sh b/scripts/plugin-changelog-release-boundaries.test.sh index c219d68..7fdc8dc 100644 --- a/scripts/plugin-changelog-release-boundaries.test.sh +++ b/scripts/plugin-changelog-release-boundaries.test.sh @@ -18,31 +18,29 @@ fresh() { git -C "$d" config user.name Fixture git -C "$d" config user.email fixture@example.invalid git -C "$d" config commit.gpgsign false - mkdir -p "$d/.claude-plugin" "$d/.github/plugin" + mkdir -p "$d/.claude-plugin" for n in alpha beta; do mkdir -p "$d/plugins/$n/.claude-plugin" "$d/plugins/$n/skills/example" - printf '{"name":"%s","version":"1.2.3"}\n' "$n" > "$d/plugins/$n/plugin.json" - cp "$d/plugins/$n/plugin.json" "$d/plugins/$n/.claude-plugin/plugin.json" + printf '{"name":"%s","version":"1.2.3"}\n' "$n" > "$d/plugins/$n/.claude-plugin/plugin.json" printf '%s\n' '---' 'name: example' 'metadata:' ' github-repo: https://github.com/example/fixture-skills' ' github-ref: refs/tags/v1.0.0' '---' 'Example.' > "$d/plugins/$n/skills/example/SKILL.md" printf '## 1.2.3 — 2026-01-01\n\nOriginal history.\n' > "$d/plugins/$n/CHANGELOG.md" done printf '%s\n' '{"name":"fixture","plugins":[{"name":"alpha","version":"1.2.3","source":"./plugins/alpha"},{"name":"beta","version":"1.2.3","source":"./plugins/beta"}]}' > "$d/.claude-plugin/marketplace.json" - cp "$d/.claude-plugin/marketplace.json" "$d/.github/plugin/marketplace.json" - git -C "$d" add -- plugins .claude-plugin .github + git -C "$d" add -- plugins .claude-plugin git -C "$d" commit -qm base base=$(git -C "$d" rev-parse HEAD) sed 's/v1.0.0/v2.0.0/' "$d/plugins/alpha/skills/example/SKILL.md" > "$d/next" mv "$d/next" "$d/plugins/alpha/skills/example/SKILL.md" git -C "$d" add -- plugins/alpha/skills/example/SKILL.md git -C "$d" commit -qm sync - printf '%s\n' '{"name":"alpha","version":"1.2.4"}' > "$d/plugins/alpha/plugin.json" + printf '%s\n' '{"name":"alpha","version":"1.2.4"}' > "$d/plugins/alpha/.claude-plugin/plugin.json" } # Capture only the actual helper's status and bytes, preserving later assertions. run() { rc=0; (cd "$d" && "$@") > "$work/out" 2> "$work/err" || rc=$?; } # Commit only the fixture-owned plugin paths. commit() { git -C "$d" add -- plugins; git -C "$d" commit -qm change; } # Snapshot all publication files independently of the index. -snapshot() { find "$d/plugins" "$d/.claude-plugin" "$d/.github" -type f -exec cksum {} + | LC_ALL=C sort; } +snapshot() { find "$d/plugins" "$d/.claude-plugin" -type f -exec cksum {} + | LC_ALL=C sort; } for mode in check write; do for selector in repository worktree index config; do fresh @@ -111,7 +109,7 @@ commit; snapshot > "$work/before" run bash "$here/plugin-changelog.sh" write "$base" 2026-10-04 label='nonregular committed provenance refuses'; check test "$rc" -ne 0 snapshot > "$work/after"; label='nonregular committed provenance preserves batch'; check cmp "$work/before" "$work/after" -for target in marketplace portable; do +for target in marketplace plugin; do for kind in scalar container escaped; do fresh if [[ $target == marketplace ]]; then @@ -121,11 +119,11 @@ for target in marketplace portable; do container) printf '%s\n' '{"plugins":[{"name":"beta","version":"1.2.3"}],"plugins":[{"name":"alpha","version":"1.2.3","source":"./plugins/alpha"}]}' > "$file" ;; escaped) printf '%s\n' '{"plugins":[],"\u0070lugins":[{"name":"alpha","version":"1.2.3","source":"./plugins/alpha"}]}' > "$file" ;; esac - cp "$d/plugins/alpha/.claude-plugin/plugin.json" "$d/plugins/alpha/plugin.json" + printf '{"name":"alpha","version":"1.2.3"}\n' > "$d/plugins/alpha/.claude-plugin/plugin.json" snapshot > "$work/before" run bash "$here/bump-plugin-version.sh" alpha patch else - file="$d/plugins/alpha/plugin.json" + file="$d/plugins/alpha/.claude-plugin/plugin.json" case $kind in scalar) printf '%s\n' '{"version":"1.2.4","version":"1.2.3"}' > "$file" ;; container) printf '%s\n' '{"version":"1.2.3","extra":{},"extra":{}}' > "$file" ;; @@ -141,7 +139,7 @@ done for mode in check write; do fresh tree=$(git -C "$d" rev-parse "$base^{tree}") - git -C "$d" add -- plugins/alpha/plugin.json + git -C "$d" add -- plugins/alpha/.claude-plugin/plugin.json changed_tree=$(git -C "$d" write-tree) a=$(printf 'First base\n' | git -C "$d" commit-tree "$changed_tree" -p "$base") b=$(printf 'Other base\n' | git -C "$d" commit-tree "$tree" -p "$base") diff --git a/scripts/plugin-changelog.sh b/scripts/plugin-changelog.sh index 0d90772..cdfb473 100644 --- a/scripts/plugin-changelog.sh +++ b/scripts/plugin-changelog.sh @@ -89,7 +89,7 @@ while IFS= read -r dir; do fi done fi - manifest="$dir/plugin.json" + manifest="$dir/.claude-plugin/plugin.json" old='' base_entry=$(git ls-tree "$base" -- "$manifest") || fail "unreadable base manifest tree: $name" if [ -n "$base_entry" ]; then diff --git a/scripts/plugin-changelog.test.sh b/scripts/plugin-changelog.test.sh index 642b081..858e057 100644 --- a/scripts/plugin-changelog.test.sh +++ b/scripts/plugin-changelog.test.sh @@ -13,8 +13,8 @@ fixture() { git -C "$dir" config user.email test@example.invalid git -C "$dir" config commit.gpgsign false for plugin in alpha beta; do - mkdir -p "$dir/plugins/$plugin/skills/example" - printf '{"version":"1.2.3"}\n' > "$dir/plugins/$plugin/plugin.json" + mkdir -p "$dir/plugins/$plugin/skills/example" "$dir/plugins/$plugin/.claude-plugin" + printf '{"version":"1.2.3"}\n' > "$dir/plugins/$plugin/.claude-plugin/plugin.json" cat > "$dir/plugins/$plugin/skills/example/SKILL.md" <<'MD' --- name: example @@ -34,8 +34,8 @@ MD git -C "$dir" add -- plugins/alpha/skills/example/SKILL.md git -C "$dir" commit -qm sync } -# Simulate the four-manifest helper's resulting portable version, which this tool reads. -bump() { printf '{"version":"1.2.4"}\n' > "$dir/plugins/alpha/plugin.json"; } +# Simulate the version helper's resulting plugin manifest version, which this tool reads. +bump() { printf '{"version":"1.2.4"}\n' > "$dir/plugins/alpha/.claude-plugin/plugin.json"; } # The check reads committed output, matching its CI boundary. commit() { git -C "$dir" add -- plugins; git -C "$dir" commit -qm change; } # Run the real tool in the fixture and assert failure is never mistaken for a pass. @@ -220,7 +220,7 @@ cmp "$work/before" "$dir/plugins/alpha/CHANGELOG.md" fixture git -C "$dir" checkout -qb feature git -C "$dir" checkout -qb advanced "$base" -printf '{"version":"1.2.4"}\n' > "$dir/plugins/beta/plugin.json" +printf '{"version":"1.2.4"}\n' > "$dir/plugins/beta/.claude-plugin/plugin.json" commit advanced=$(git -C "$dir" rev-parse HEAD) git -C "$dir" checkout -q feature @@ -307,18 +307,18 @@ for kind in bullet ordered nested quote html; do done # The manifest is listed in the retained base tree, but its unique blob is missing. fixture -jq '.identity="alpha"' "$dir/plugins/alpha/plugin.json" > "$work/manifest" -cp "$work/manifest" "$dir/plugins/alpha/plugin.json" +jq '.identity="alpha"' "$dir/plugins/alpha/.claude-plugin/plugin.json" > "$work/manifest" +cp "$work/manifest" "$dir/plugins/alpha/.claude-plugin/plugin.json" commit base=$(git -C "$dir" rev-parse HEAD) -blob=$(git -C "$dir" rev-parse "$base:plugins/alpha/plugin.json") +blob=$(git -C "$dir" rev-parse "$base:plugins/alpha/.claude-plugin/plugin.json") printf '\nnew sync\n' >> "$dir/plugins/alpha/skills/example/SKILL.md" bump; commit cp "$dir/plugins/alpha/CHANGELOG.md" "$work/unchanged" rm "$dir/.git/objects/${blob:0:2}/${blob:2}" git -C "$dir" cat-file -e "$base^{commit}" -[ -n "$(git -C "$dir" ls-tree "$base" -- plugins/alpha/plugin.json)" ] -if git -C "$dir" show "$base:plugins/alpha/plugin.json" >/dev/null 2>&1; then exit 1; fi +[ -n "$(git -C "$dir" ls-tree "$base" -- plugins/alpha/.claude-plugin/plugin.json)" ] +if git -C "$dir" show "$base:plugins/alpha/.claude-plugin/plugin.json" >/dev/null 2>&1; then exit 1; fi refuse write "$base" 2026-10-02 grep -q 'unreadable base manifest' "$work/out" cmp "$work/unchanged" "$dir/plugins/alpha/CHANGELOG.md" @@ -335,7 +335,7 @@ passed=$((passed + 1)) # Removing an authored skill retains its former source revision. base=$(git -C "$dir" rev-parse HEAD) -printf '{"version":"1.2.5"}\n' > "$dir/plugins/alpha/plugin.json" +printf '{"version":"1.2.5"}\n' > "$dir/plugins/alpha/.claude-plugin/plugin.json" rm "$dir/plugins/alpha/skills/example/SKILL.md" commit (cd "$dir" && bash "$script" write "$base" 2026-11-01) diff --git a/scripts/plugin-scorecard.sh b/scripts/plugin-scorecard.sh index 13bc8b5..1d623c9 100755 --- a/scripts/plugin-scorecard.sh +++ b/scripts/plugin-scorecard.sh @@ -27,7 +27,7 @@ snapshot() { [ "$bytes" -le 33554432 ] || fail 'input budget exceeds 32 MiB' json_object_unique "$work/input" || fail 'input is not one unambiguous JSON object' } -snapshot "$root/.github/plugin/marketplace.json" +snapshot "$root/.claude-plugin/marketplace.json" cp "$work/input" "$work/catalogue" while [ "$#" -gt 0 ]; do case "$1" in diff --git a/scripts/plugin-version-boundaries.test.sh b/scripts/plugin-version-boundaries.test.sh index d0fddf1..623c57a 100644 --- a/scripts/plugin-version-boundaries.test.sh +++ b/scripts/plugin-version-boundaries.test.sh @@ -16,20 +16,18 @@ fresh() { git -C "$d" config user.name Fixture git -C "$d" config user.email fixture@example.test git -C "$d" config commit.gpgsign false - mkdir -p "$d/.claude-plugin" "$d/.github/plugin" "$d/plugins/alpha/.claude-plugin" "$d/plugins/beta/.claude-plugin" + mkdir -p "$d/.claude-plugin" "$d/plugins/alpha/.claude-plugin" "$d/plugins/beta/.claude-plugin" for name in alpha beta; do - printf '{"name":"%s","version":"1.2.3"}\n' "$name" > "$d/plugins/$name/plugin.json" - cp "$d/plugins/$name/plugin.json" "$d/plugins/$name/.claude-plugin/plugin.json" + printf '{"name":"%s","version":"1.2.3"}\n' "$name" > "$d/plugins/$name/.claude-plugin/plugin.json" printf 'original\n' > "$d/plugins/$name/body.md" done printf '%s\n' '{"name":"fixture","plugins":[{"name":"alpha","version":"1.2.3","source":"./plugins/alpha"},{"name":"beta","version":"1.2.3","source":"./plugins/beta"}]}' > "$d/.claude-plugin/marketplace.json" - cp "$d/.claude-plugin/marketplace.json" "$d/.github/plugin/marketplace.json" - git -C "$d" add plugins .claude-plugin .github + git -C "$d" add plugins .claude-plugin git -C "$d" commit -qm base git -C "$d" checkout -qb feature } # Commit only the fixture's plugin and marketplace paths at the current branch. -commit() { git -C "$d" add plugins .claude-plugin .github; git -C "$d" commit -qm change; } +commit() { git -C "$d" add plugins .claude-plugin; git -C "$d" commit -qm change; } # Capture the real guard's status and output against this fixture's main and HEAD. run_gate() { rc=0; (cd "$d" && bash "$here/check-plugin-version-bump.sh" main HEAD) > "$work/out" 2> "$work/err" || rc=$?; } # Capture the real changed-since writer's status and output without exiting the test. @@ -37,8 +35,8 @@ run_writer() { rc=0; (cd "$d" && bash "$here/bump-plugin-version.sh" --changed-s # Snapshot actual preservation evidence independently of Git's index and ancestry. preservation_snapshot() { { - find "$d/plugins" "$d/.claude-plugin" "$d/.github" -type f -exec shasum {} + - find "$d/plugins" "$d/.claude-plugin" "$d/.github" -type l \ + find "$d/plugins" "$d/.claude-plugin" -type f -exec shasum {} + + find "$d/plugins" "$d/.claude-plugin" -type l \ -exec bash -c 'printf "%s -> %s\n" "$1" "$(readlink "$1")"' _ {} \; if [ -f "$d/alternate.json" ]; then shasum "$d/alternate.json"; fi } | LC_ALL=C sort @@ -49,7 +47,7 @@ for tool in gate writer; do git -C "$d" replace HEAD "$replacement" "run_$tool" if [[ $tool == gate ]]; then label='replacement objects cannot hide an unbumped change'; check test "$rc" -ne 0 - else label='writer bumps original committed content despite replacement objects'; check test "$(jq -r .version "$d/plugins/alpha/plugin.json")" = 1.2.4; fi + else label='writer bumps original committed content despite replacement objects'; check test "$(jq -r .version "$d/plugins/alpha/.claude-plugin/plugin.json")" = 1.2.4; fi fresh; printf 'changed\n' > "$d/plugins/alpha/body.md"; commit changed_head=$(git -C "$d" rev-parse HEAD) @@ -63,7 +61,7 @@ for tool in gate writer; do printf 'changed\n' > "$d/plugins/alpha/body.md"; commit GIT_DIR="$foreign/.git" GIT_WORK_TREE="$foreign" "run_$tool" if [[ $tool == gate ]]; then label='caller Git context cannot clear the current checkout'; check test "$rc" -ne 0 - else label='writer reads the current checkout despite caller Git context'; check test "$(jq -r .version "$d/plugins/alpha/plugin.json")" = 1.2.4; fi + else label='writer reads the current checkout despite caller Git context'; check test "$(jq -r .version "$d/plugins/alpha/.claude-plugin/plugin.json")" = 1.2.4; fi fresh printf '%s\n' '{"name":"alpha","version":"1.2.3","version":"1.2.2"}' > "$d/plugins/alpha/.claude-plugin/plugin.json" @@ -86,10 +84,9 @@ for tool in gate writer; do for name in alpha beta; do printf 'changed\n' > "$d/plugins/$name/body.md" printf '{"name":"%s","version":"1.2.4"}\n' "$name" > "$d/plugins/$name/.claude-plugin/plugin.json" - cp "$d/plugins/$name/.claude-plugin/plugin.json" "$d/plugins/$name/plugin.json" done jq '.plugins[].version="1.2.4"' "$d/.claude-plugin/marketplace.json" > "$d/next"; mv "$d/next" "$d/.claude-plugin/marketplace.json" - cp "$d/.claude-plugin/marketplace.json" "$d/.github/plugin/marketplace.json"; commit + commit mkdir -p "$work/bin" cat > "$work/bin/git" <<'EOF' #!/usr/bin/env bash @@ -114,11 +111,11 @@ fresh; run_gate label='complete unchanged plugin census succeeds'; check test "$rc" -eq 0 fresh; printf 'changed\n' > "$d/plugins/alpha/body.md"; commit run_writer; label='ordinary changed-since writer succeeds'; check test "$rc" -eq 0 -label='ordinary writer updates the selected plugin'; check test "$(jq -r .version "$d/plugins/alpha/plugin.json")" = 1.2.4 -label='ordinary writer preserves its sibling'; check test "$(jq -r .version "$d/plugins/beta/plugin.json")" = 1.2.3 +label='ordinary writer updates the selected plugin'; check test "$(jq -r .version "$d/plugins/alpha/.claude-plugin/plugin.json")" = 1.2.4 +label='ordinary writer preserves its sibling'; check test "$(jq -r .version "$d/plugins/beta/.claude-plugin/plugin.json")" = 1.2.3 commit; run_gate; label='committed generated bump satisfies the gate'; check test "$rc" -eq 0 run_writer; label='repeated changed-since remains idempotent'; check test "$rc" -eq 0 -label='repeated writer retains the cache version'; check test "$(jq -r .version "$d/plugins/alpha/plugin.json")" = 1.2.4 +label='repeated writer retains the cache version'; check test "$(jq -r .version "$d/plugins/alpha/.claude-plugin/plugin.json")" = 1.2.4 for mode in repeated-head multi-head symlink-head shallow promisor; do fresh printf 'changed\n' > "$d/plugins/alpha/body.md" diff --git a/scripts/publish-skill-metadata.sh b/scripts/publish-skill-metadata.sh index ad9070d..ee8b07d 100644 --- a/scripts/publish-skill-metadata.sh +++ b/scripts/publish-skill-metadata.sh @@ -81,7 +81,7 @@ while IFS=$'\t' read -r status path extra || [ -n "${status}${path}${extra}" ]; fail 'metadata changes must be regular-file additions or modifications' fi case "$path" in - .claude-plugin/marketplace.json | .github/plugin/marketplace.json | "plugins/$plugin/plugin.json" | "plugins/$plugin/.claude-plugin/plugin.json" | "plugins/$plugin/.codex-plugin/plugin.json" | "plugins/$plugin/CHANGELOG.md") ;; + .claude-plugin/marketplace.json | "plugins/$plugin/.claude-plugin/plugin.json" | "plugins/$plugin/.codex-plugin/plugin.json" | "plugins/$plugin/CHANGELOG.md") ;; "plugins/$plugin/resources/"*) resource=${path#"plugins/$plugin/resources/"} [[ "$resource" =~ ^[A-Za-z0-9_-][A-Za-z0-9_.-]*\.desired-state\.json$ ]] || fail 'unexpected resource path' diff --git a/scripts/publish-skill-metadata.test.sh b/scripts/publish-skill-metadata.test.sh index 0dbf795..ff4557f 100644 --- a/scripts/publish-skill-metadata.test.sh +++ b/scripts/publish-skill-metadata.test.sh @@ -15,8 +15,8 @@ git -C "$work/base" init -q git -C "$work/base" config user.name Fixture git -C "$work/base" config user.email fixture@example.invalid git -C "$work/base" remote add origin https://github.com/devantler-tech/agent-plugins.git -paths=(.claude-plugin/marketplace.json .github/plugin/marketplace.json - "$plugin/plugin.json" "$plugin/.claude-plugin/plugin.json" "$plugin/.codex-plugin/plugin.json" +paths=(.claude-plugin/marketplace.json + "$plugin/.claude-plugin/plugin.json" "$plugin/.codex-plugin/plugin.json" "$plugin/resources/provider-neutral.desired-state.json" "$plugin/CHANGELOG.md") for path in "${paths[@]}"; do mkdir -p "$work/base/$(dirname "$path")" @@ -104,7 +104,7 @@ export PATH="$work/bin:$PATH" # Reset each isolated fixture and stage an exact metadata union; keep unrelated edits unstaged. fixture() { - local selected=("$plugin/plugin.json") + local selected=("$plugin/.claude-plugin/plugin.json") if [ "${1:-}" = full ]; then selected=("${paths[@]}"); fi rm -rf "$FIXTURE" "$STATE" cp -R "$work/base" "$FIXTURE" @@ -153,7 +153,7 @@ publish [ "$(git -C "$FIXTURE" write-tree)" = "$before_tree" ] git -C "$FIXTURE" diff >"$STATE/unstaged-after" cmp "$STATE/unstaged-before" "$STATE/unstaged-after" -jq -e '.variables.input.fileChanges.additions|length==7 and all(.[];.path!="unrelated")' "$STATE/request" >/dev/null +jq -e '.variables.input.fileChanges.additions|length==5 and all(.[];.path!="unrelated")' "$STATE/request" >/dev/null printf 'PASS: one signed request reproduces every staged byte and preserves the caller\n' # A changelog can outgrow Linux's per-argument limit and macOS's total argument budget. @@ -188,7 +188,7 @@ for mode in race unsigned partial-write bad-readback-signature wrong-tree wrong- reject "$mode" after done fixture -printf '{"later":"editor"}\n' >"$FIXTURE/$plugin/plugin.json" +printf '{"later":"editor"}\n' >"$FIXTURE/$plugin/.claude-plugin/plugin.json" reject unstaged-metadata before fixture git -C "$FIXTURE" remote set-url origin https://github.com/other/agent-plugins.git @@ -197,22 +197,30 @@ fixture printf 'outside\n' >"$FIXTURE/forbidden" git -C "$FIXTURE" add -- forbidden reject forbidden-path before +# The retired duplicate manifests are outside the metadata a sync may publish. +for retired in .github/plugin/marketplace.json "$plugin/plugin.json"; do + fixture + mkdir -p "$FIXTURE/$(dirname "$retired")" + printf '{"after":true}\n' >"$FIXTURE/$retired" + git -C "$FIXTURE" add -- "$retired" + reject "retired-manifest $retired" before +done fixture rm "$FIXTURE/$plugin/CHANGELOG.md" git -C "$FIXTURE" add -- "$plugin/CHANGELOG.md" reject deletion before fixture rm "$FIXTURE/$plugin/CHANGELOG.md" -ln -s ../plugin.json "$FIXTURE/$plugin/CHANGELOG.md" +ln -s .claude-plugin/plugin.json "$FIXTURE/$plugin/CHANGELOG.md" git -C "$FIXTURE" add -- "$plugin/CHANGELOG.md" reject symlink before fixture -printf '{"value":1,"value":2}\n' >"$FIXTURE/$plugin/plugin.json" -git -C "$FIXTURE" add -- "$plugin/plugin.json" +printf '{"value":1,"value":2}\n' >"$FIXTURE/$plugin/.claude-plugin/plugin.json" +git -C "$FIXTURE" add -- "$plugin/.claude-plugin/plugin.json" reject duplicate-json before fixture -printf '{"value":' >"$FIXTURE/$plugin/plugin.json" -git -C "$FIXTURE" add -- "$plugin/plugin.json" +printf '{"value":' >"$FIXTURE/$plugin/.claude-plugin/plugin.json" +git -C "$FIXTURE" add -- "$plugin/.claude-plugin/plugin.json" reject partial-json before fixture printf '{}\n' >"$FIXTURE/$plugin/resources/new.desired-state.json" diff --git a/scripts/validate-manifests.sh b/scripts/validate-manifests.sh index 795918d..239a7ad 100755 --- a/scripts/validate-manifests.sh +++ b/scripts/validate-manifests.sh @@ -1,13 +1,15 @@ #!/usr/bin/env bash -# Validate the plugin marketplace manifests, every plugins//plugin.json, and the -# plugin catalogue table. +# Validate the plugin marketplace manifest, every plugins//.claude-plugin/plugin.json, +# and the plugin catalogue table. # # Single source of truth for the checks the 🧪 CI "Validate manifests" job runs: -# 1. Both marketplace manifests (Copilot + Claude) are well-formed (.name + .plugins). -# 2. The two manifests are byte-for-byte equivalent (key-sorted) — no drift. +# 1. The repository ships ONE manifest set: .claude-plugin/marketplace.json and each +# plugins//.claude-plugin/plugin.json (plus the optional Codex-specific +# .codex-plugin/plugin.json). A second marketplace or plugin manifest that a consumer +# would read first is refused, so no tool can be offered a divergent copy. +# 2. The marketplace manifest is well-formed (.name + .plugins). # 3. Append-only plugin rename history resolves to a current plugin or an explicit removal. -# 4. Every plugins//plugin.json is complete and well-shaped, and has an -# equivalent .claude-plugin/plugin.json for strict Claude ingestion. +# 4. Every plugins//.claude-plugin/plugin.json is complete and well-shaped. # 5. Manifest entries and on-disk plugins are in lockstep (no missing/orphan plugin, # no name/description/version/source divergence). # 6. The plugin catalogue table and on-disk plugin resources are in lockstep (every plugin @@ -23,7 +25,6 @@ # stop-on-first-failing-step behaviour. set -euo pipefail -COPILOT_MANIFEST=".github/plugin/marketplace.json" CLAUDE_MANIFEST=".claude-plugin/marketplace.json" RENAME_HISTORY="scripts/marketplace-rename-history.json" README="docs/plugins.md" @@ -84,12 +85,33 @@ validate_package_boundaries() { echo "::error::$package: package names must be kebab-case"; return 1 fi if [ -L "$package" ] || - ! regular_packaged_file "$package/plugin.json" || ! regular_packaged_file "$package/.claude-plugin/plugin.json"; then - echo "::error::$package: every package requires its own regular canonical manifests"; return 1 + echo "::error::$package: every package requires its own regular canonical manifest .claude-plugin/plugin.json"; return 1 fi done < "$inventory_dir/packages" } + +# 1. One manifest set. VS Code reads marketplace.json, .plugin/marketplace.json and +# .github/plugin/marketplace.json before .claude-plugin/marketplace.json, and a plugin's +# .plugin/plugin.json before .claude-plugin/plugin.json and plugin.json after it. Any of those +# copies would either shadow the canonical manifest for that tool or drift beside it, so the +# repository refuses them instead of keeping them in parity. +validate_single_manifest_set() { + local path package + for path in marketplace.json .plugin/marketplace.json .github/plugin/marketplace.json; do + if [ -e "$path" ] || [ -L "$path" ]; then + echo "::error::$path: the marketplace has one manifest, $CLAUDE_MANIFEST; remove this copy"; return 1 + fi + done + while IFS= read -r -d '' package; do + for path in "$package/plugin.json" "$package/.plugin/plugin.json"; do + if [ -e "$path" ] || [ -L "$path" ]; then + echo "::error::$path: a plugin has one manifest, $package/.claude-plugin/plugin.json; remove this copy"; return 1 + fi + done + done < "$inventory_dir/packages" + echo "✓ One marketplace and plugin manifest set" +} # Default skill discovery includes every direct directory, not just complete matches. validate_skill_dir() { local dir=$1 child count=0 @@ -111,7 +133,7 @@ validate_skill_dir() { [ "$count" -gt 0 ] || { echo "::error::$dir: 'skills/' present but contains no /SKILL.md"; return 1; } } -# 1. A marketplace manifest must parse and carry both required top-level keys. +# 2. The marketplace manifest must parse and carry both required top-level keys. validate_marketplace_json() { local manifest="$1" if ! regular_packaged_file "$manifest"; then echo "::error::$manifest: manifest must be a regular packaged file"; return 1; fi @@ -131,33 +153,6 @@ validate_marketplace_json() { echo "✓ $manifest is valid" } -# Capture each producer's status explicitly: diff cannot observe a failed jq -# inside process substitution, even when both producers print nothing. -validate_json_parity() { - local left="$1" right="$2" mismatch="$3" left_json right_json - if ! left_json=$(jq -S . "$left"); then - echo "::error::Could not normalize $left" - return 1 - fi - if ! right_json=$(jq -S . "$right"); then - echo "::error::Could not normalize $right" - return 1 - fi - if [ "$left_json" != "$right_json" ]; then - echo "::error::$mismatch" - # Diagnostic only; the checked, captured values above decide parity. - diff -u <(printf '%s\n' "$left_json") <(printf '%s\n' "$right_json") || true - return 1 - fi -} - -# 2. The Copilot and Claude manifests must be identical once key-sorted. -validate_marketplace_parity() { - validate_json_parity "$COPILOT_MANIFEST" "$CLAUDE_MANIFEST" \ - 'Marketplace manifests are out of sync' || return 1 - echo "✓ Marketplace manifests are in sync" -} - # 3. Claude Code persists qualified plugin names in enabledPlugins and pluginConfigs. # Once this marketplace renames or retires a plugin, its top-level `renames` history is # therefore a permanent compatibility contract: sources must be retired kebab-case names, @@ -454,12 +449,12 @@ validate_codex_mcp_mirror() { # An optional Codex manifest (ADR 0019). Codex reads .codex-plugin/plugin.json before # .claude-plugin/plugin.json and resolves only the component paths it declares, so it must repeat -# the portable manifest exactly, name the plugin's own skills/ and .mcp.json, and add nothing else +# the canonical manifest exactly, name the plugin's own skills/ and .mcp.json, and add nothing else # but an app list and a listing interface. Every app it offers is optional: installing the plugin # must never require a connector the user has not chosen. validate_codex_manifest() { local pj="$1" plugin_dir="$2" codex_pj="$2/.codex-plugin/plugin.json" apps="$2/.app.json" - local portable_json codex_json ok=1 + local canonical_json codex_json ok=1 if [ ! -e "$codex_pj" ] && [ ! -L "$codex_pj" ]; then if [ -e "$apps" ] || [ -L "$apps" ]; then echo "::error::$apps: Codex apps must be declared by $codex_pj"; return 1 @@ -470,11 +465,11 @@ validate_codex_manifest() { echo "::error::$codex_pj: the Codex manifest must be a regular packaged file"; return 1 fi if ! json_object_unique "$codex_pj"; then echo "::error::Invalid $codex_pj"; return 1; fi - if ! portable_json=$(jq -S . "$pj") || + if ! canonical_json=$(jq -S . "$pj") || ! codex_json=$(jq -S 'del(.skills, .mcpServers, .apps, .interface)' "$codex_pj"); then echo "::error::Could not normalize $codex_pj"; return 1 fi - if [ "$portable_json" != "$codex_json" ]; then + if [ "$canonical_json" != "$codex_json" ]; then echo "::error::$codex_pj differs from $pj beyond Codex's skills, mcpServers, apps and interface" ok=0 fi @@ -537,16 +532,15 @@ validate_codex_manifest() { [ "$ok" -eq 1 ] } -# 4. Every plugins//plugin.json is complete and well-shaped, has an equivalent -# .claude-plugin/plugin.json for strict Claude marketplace ingestion, and declares -# at least one recognized resource (skills/, a bundled .mcp.json, or agents/) — -# ADR 0001 §D3. +# 4. Every plugins//.claude-plugin/plugin.json is complete and well-shaped and +# declares at least one recognized resource (skills/, a bundled .mcp.json, or agents/) — +# ADR 0001 §D3. Claude Code, Claude Desktop's strict remote ingestion, VS Code and the +# Copilot CLI all read this canonical path. validate_plugin_json() { local failed=0 - local pj plugin_dir claude_pj ok plugin_name resource_count - for pj in plugins/*/plugin.json; do - plugin_dir=$(dirname "$pj") - claude_pj="$plugin_dir/.claude-plugin/plugin.json" + local pj plugin_dir ok plugin_name resource_count + for pj in plugins/*/.claude-plugin/plugin.json; do + plugin_dir=$(dirname "$(dirname "$pj")") ok=1 resource_count=0 if ! json_object_unique "$pj"; then @@ -567,19 +561,6 @@ validate_plugin_json() { echo "::error::$pj: missing or empty 'version', or not a canonical stable cache version" ok=0 fi - # Claude Desktop's remote marketplace service validates sourced plugins in strict - # mode and requires the canonical .claude-plugin/plugin.json path. Copilot/VS Code - # consume the portable top-level plugin.json, so keep both normalized JSON documents - # equivalent rather than letting either provider receive a divergent contract. - if [ ! -f "$claude_pj" ]; then - echo "::error::$plugin_dir requires .claude-plugin/plugin.json for strict Claude marketplace ingestion" - ok=0 - elif ! json_object_unique "$claude_pj"; then - echo "::error::Invalid $claude_pj" - ok=0 - elif ! validate_json_parity "$pj" "$claude_pj" "$claude_pj differs from $pj"; then - ok=0 - fi if ! validate_codex_manifest "$pj" "$plugin_dir"; then ok=0; fi # This marketplace's portable component-path contract requires arrays when # skills/agents are declared. Omission retains default directory discovery. @@ -637,7 +618,7 @@ validate_marketplace_plugins_parity() { echo "::error::$manifest: plugin '$name' source '$source' must be './plugins/$name'" ok=0 fi - pj="plugins/$name/plugin.json" + pj="plugins/$name/.claude-plugin/plugin.json" if ! regular_packaged_file "$pj"; then echo "::error::$manifest: plugin '$name' has no $pj on disk"; failed=1; continue fi @@ -678,8 +659,8 @@ plugin_disk_resources() { if [ -f "$mcp" ]; then jq -r '.mcpServers // {} | keys[]' "$mcp" fi - if jq -e 'has("agents")' "plugins/$name/plugin.json" >/dev/null; then - jq -r '.agents[] | split("/")[-1] | sub("\\.agent\\.md$"; "")' "plugins/$name/plugin.json" + if jq -e 'has("agents")' "plugins/$name/.claude-plugin/plugin.json" >/dev/null; then + jq -r '.agents[] | split("/")[-1] | sub("\\.agent\\.md$"; "")' "plugins/$name/.claude-plugin/plugin.json" else for d in "plugins/$name/agents"/*.agent.md; do [ -e "$d" ] || continue @@ -721,10 +702,10 @@ validate_readme_parity() { readme_resources=$(printf '%s' "$line" | awk -F'|' '{print $3}' \ | grep -oE '`[^`][^`]*`' | tr -d '`' | sort | tr '\n' ' ') # Require the manifest, not just the directory: a stray plugins// without a - # plugin.json would otherwise pass here yet stay invisible to the orphan scan below - # (which only iterates plugins/*/plugin.json). - if [ ! -f "plugins/$name/plugin.json" ]; then - echo "::error::$README lists plugin '$name' with no plugins/$name/plugin.json on disk" + # .claude-plugin/plugin.json would otherwise pass here yet stay invisible to the orphan scan + # below (which only iterates plugins/*/.claude-plugin/plugin.json). + if [ ! -f "plugins/$name/.claude-plugin/plugin.json" ]; then + echo "::error::$README lists plugin '$name' with no plugins/$name/.claude-plugin/plugin.json on disk" failed=1 continue fi @@ -738,7 +719,7 @@ validate_readme_parity() { done < "$inventory_dir/catalogue" # Every plugins// on disk appears as a catalogue row (no plugin missing from the table). local pj listed rn - for pj in plugins/*/plugin.json; do + for pj in plugins/*/.claude-plugin/plugin.json; do name=$(jq -r '.name' "$pj") listed=0 for rn in "${readme_names[@]}"; do @@ -837,8 +818,8 @@ validate_desired_state_resources() { readme="$plugin_dir/README.md" basename=$(basename "$resource") - if [ ! -f "$plugin_dir/plugin.json" ]; then - echo "::error::$resource: $plugin_dir has no plugin.json; desired-state resources must belong to a manifested plugin" + if [ ! -f "$plugin_dir/.claude-plugin/plugin.json" ]; then + echo "::error::$resource: $plugin_dir has no .claude-plugin/plugin.json; desired-state resources must belong to a manifested plugin" failed=1 continue fi @@ -1711,9 +1692,8 @@ validate_skill_provenance() { main() { validate_package_boundaries - validate_marketplace_json "$COPILOT_MANIFEST" + validate_single_manifest_set validate_marketplace_json "$CLAUDE_MANIFEST" - validate_marketplace_parity validate_marketplace_renames validate_plugin_json validate_marketplace_plugins_parity diff --git a/scripts/validate-manifests.test.sh b/scripts/validate-manifests.test.sh index ce32c6d..aa22339 100755 --- a/scripts/validate-manifests.test.sh +++ b/scripts/validate-manifests.test.sh @@ -2,7 +2,7 @@ # Self-test for validate-manifests.sh. # # Proves the guard PASSES a consistent fixture and FAILS each drift scenario it -# exists to catch — malformed manifests, manifest desync, every plugin.json +# exists to catch — malformed manifests, a second manifest copy, every plugin.json # completeness rule, and every manifest↔plugins lockstep rule — so a refactor # that silently weakens a check is caught here, not by a broken plugin reaching # consumers. Self-contained: builds throwaway fixtures, runs the REAL guard @@ -53,7 +53,7 @@ sync_entrypoint_digest() { # Build a complete, valid fixture repo (two plugins) at $1. make_fixture() { local root="$1" - mkdir -p "$root/.github/plugin" "$root/.claude-plugin" "$root/scripts" "$root/docs" + mkdir -p "$root/.claude-plugin" "$root/scripts" "$root/docs" local manifest='{ "name": "devantler-plugins", "renames": { @@ -65,7 +65,6 @@ make_fixture() { { "name": "beta", "description": "Beta plugin", "version": "1.0.0", "source": "./plugins/beta" } ] }' - printf '%s\n' "$manifest" > "$root/.github/plugin/marketplace.json" printf '%s\n' "$manifest" > "$root/.claude-plugin/marketplace.json" printf '%s\n' '{"legacy-alpha":"alpha","retired-plugin":null}' \ > "$root/scripts/marketplace-rename-history.json" @@ -82,8 +81,7 @@ make_fixture() { EOF } -# Write the portable plugins//plugin.json, its strict Claude manifest copy, -# and one skill with a SKILL.md. +# Write the canonical plugins//.claude-plugin/plugin.json and one skill with a SKILL.md. # The SKILL.md carries upstream provenance frontmatter (metadata.github-repo), exactly # as `gh skill install` records it, so the provenance guard passes on the happy path. make_plugin() { @@ -102,20 +100,14 @@ Example skill. EOF # No "skills" field: skills are auto-discovered from the on-disk skills/ dir by both # Claude Code and Copilot CLI. Claude Code rejects the bare-string "skills": "skills/" - # form, so the portable manifest omits it — the fixture mirrors the real plugins. -cat > "$root/plugins/$name/plugin.json" < "$root/plugins/$name/.claude-plugin/plugin.json" <&1 ); } @@ -125,19 +117,17 @@ run_guard() { ( cd "$1" && bash "$GUARD" 2>&1 ); } # explicit test change that reviewers can see; changing both data files alone cannot rewrite # consumer history silently. validate_published_rename_contract() { - local root="$1" manifest + local root="$1" if ! jq -e --argjson expected "$PUBLISHED_RENAMES" '. == $expected' \ "$root/scripts/marketplace-rename-history.json" > /dev/null 2>&1; then echo "must preserve every published plugin rename in the independent regression contract" return 1 fi - for manifest in "$root/.github/plugin/marketplace.json" "$root/.claude-plugin/marketplace.json"; do - if ! jq -e --argjson expected "$PUBLISHED_RENAMES" '.renames == $expected' \ - "$manifest" > /dev/null 2>&1; then - echo "must preserve every published plugin rename in the independent regression contract" - return 1 - fi - done + if ! jq -e --argjson expected "$PUBLISHED_RENAMES" '.renames == $expected' \ + "$root/.claude-plugin/marketplace.json" > /dev/null 2>&1; then + echo "must preserve every published plugin rename in the independent regression contract" + return 1 + fi } # check_pass @@ -203,27 +193,40 @@ mv "$d/skill.tmp" "$d/plugins/alpha/skills/example-skill/SKILL.md" check_fail "Matt source without a distributed notice is refused" "Matt Pocock license" "$d" check_published_contract_pass "published plugin rename mappings are independently pinned" "$REPO_ROOT" -# --- check 1: malformed marketplace manifests --- -d=$(fresh); printf '%s\n' '{"name":"x"}' > "$d/.github/plugin/marketplace.json" -check_fail "Copilot manifest missing .plugins fails" "Invalid .github/plugin/marketplace.json" "$d" +# --- check 1: one manifest set --- +# VS Code reads these copies before (or, for plugin.json, after) the canonical manifests, so a +# reintroduced copy would either shadow the canonical one for that tool or drift beside it. +for copy in marketplace.json .plugin/marketplace.json .github/plugin/marketplace.json; do + d=$(fresh); mkdir -p "$d/$(dirname "$copy")" + cp "$d/.claude-plugin/marketplace.json" "$d/$copy" + check_fail "a second marketplace manifest at $copy fails" \ + "$copy: the marketplace has one manifest, .claude-plugin/marketplace.json" "$d" +done +for copy in plugin.json .plugin/plugin.json; do + d=$(fresh); mkdir -p "$d/plugins/alpha/$(dirname "$copy")" + cp "$d/plugins/alpha/.claude-plugin/plugin.json" "$d/plugins/alpha/$copy" + check_fail "a second plugin manifest at plugins/alpha/$copy fails" \ + "plugins/alpha/$copy: a plugin has one manifest, plugins/alpha/.claude-plugin/plugin.json" "$d" +done +d=$(fresh); ln -s ../.claude-plugin/marketplace.json "$d/marketplace.json" +check_fail "a linked second marketplace manifest fails" "marketplace.json: the marketplace has one manifest" "$d" + +# --- check 2: malformed marketplace manifest --- +d=$(fresh); printf '%s\n' '{"name":"x"}' > "$d/.claude-plugin/marketplace.json" +check_fail "manifest missing .plugins fails" "Invalid .claude-plugin/marketplace.json" "$d" d=$(fresh); printf '%s\n' '{"plugins":[]}' > "$d/.claude-plugin/marketplace.json" check_fail "Claude manifest missing .name fails" "Invalid .claude-plugin/marketplace.json" "$d" -d=$(fresh); printf '%s\n' 'not json' > "$d/.github/plugin/marketplace.json" -check_fail "non-JSON manifest fails" "Invalid .github/plugin/marketplace.json" "$d" +d=$(fresh); printf '%s\n' 'not json' > "$d/.claude-plugin/marketplace.json" +check_fail "non-JSON manifest fails" "Invalid .claude-plugin/marketplace.json" "$d" -# --- check 2: manifest desync --- -d=$(fresh) -jq '.plugins[0].version = "9.9.9"' "$d/.claude-plugin/marketplace.json" > "$d/tmp" && mv "$d/tmp" "$d/.claude-plugin/marketplace.json" -check_fail "out-of-sync manifests fail" "Marketplace manifests are out of sync" "$d" - -# A failed producer in process substitution must never become a successful diff -# of two empty (or partial, matching) outputs. Exercise both manifest pairs using -# the real guard; leave jq's other validation operations unchanged. +# A failed producer in process substitution must never become a successful comparison +# of two empty (or partial, matching) outputs. The Codex manifest section below uses this +# stub against the real guard; it leaves jq's other validation operations unchanged. REAL_JQ=$(command -v jq) mkdir -p "$WORK/normalization-bin" -cat > "$WORK/normalization-bin/jq" <<'EOF' +cat > "$WORK/normalization-bin/jq" <<'STUB' #!/usr/bin/env bash if [ "${1:-}" = -S ] && [ "${2:-}" = . ]; then case "${3:-}" in @@ -235,154 +238,98 @@ if [ "${1:-}" = -S ] && [ "${2:-}" = . ]; then esac fi exec "$REAL_JQ" "$@" -EOF +STUB chmod +x "$WORK/normalization-bin/jq" -for scope in marketplace plugin; do - if [ "$scope" = marketplace ]; then - left=.github/plugin/marketplace.json - right=.claude-plugin/marketplace.json - both='*/marketplace.json' - else - left=plugins/alpha/plugin.json - right=plugins/alpha/.claude-plugin/plugin.json - both='plugins/alpha/*plugin.json' - fi - for side in left right both; do - case "$side" in - left) pattern=$left; expected=$left ;; - right) pattern=$right; expected=$right ;; - both) pattern=$both; expected=$left ;; - esac - for output in empty partial; do - d=$(fresh) - PATH="$WORK/normalization-bin:$PATH" REAL_JQ="$REAL_JQ" \ - JQ_FAILURE_PATTERN="$pattern" JQ_FAILURE_OUTPUT="$output" \ - check_fail "$scope $side normalization failure with $output output fails" \ - "Could not normalize $expected" "$d" - done - done -done - -d=$(fresh) -jq 'to_entries | reverse | from_entries' "$d/.claude-plugin/marketplace.json" > "$d/tmp" \ - && mv "$d/tmp" "$d/.claude-plugin/marketplace.json" -jq 'to_entries | reverse | from_entries' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" \ - && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" -check_pass "key order may differ in marketplace and plugin manifests" "$d" # --- check 3: append-only plugin rename history --- # Once a marketplace has renamed or retired a plugin, Claude Code needs the top-level # renames map forever so persisted enabledPlugins keys can migrate instead of becoming # orphaned. The guard must fail closed if that history disappears or stops resolving. d=$(fresh) -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq 'del(.renames)' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq 'del(.renames)' "$m" > "$d/tmp" && mv "$d/tmp" "$m" check_fail "missing plugin rename history fails" "must declare non-empty top-level 'renames' migration history" "$d" d=$(fresh) -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq '.renames = []' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq '.renames = []' "$m" > "$d/tmp" && mv "$d/tmp" "$m" check_fail "non-object plugin rename history fails" "must declare non-empty top-level 'renames' migration history" "$d" d=$(fresh) -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq 'del(.renames["legacy-alpha"])' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq 'del(.renames["legacy-alpha"])' "$m" > "$d/tmp" && mv "$d/tmp" "$m" check_fail "persisted plugin rename removal fails" "must preserve every persisted plugin rename" "$d" d=$(fresh) -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq 'del(.renames["retired-plugin"])' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq 'del(.renames["retired-plugin"])' "$m" > "$d/tmp" && mv "$d/tmp" "$m" check_fail "persisted null retirement removal fails" "must preserve every persisted plugin rename" "$d" d=$(mktemp -d "$WORK/published-contract-XXXXXX") -mkdir -p "$d/.github/plugin" "$d/.claude-plugin" "$d/scripts" -cp "$REPO_ROOT/.github/plugin/marketplace.json" "$d/.github/plugin/marketplace.json" +mkdir -p "$d/.claude-plugin" "$d/scripts" cp "$REPO_ROOT/.claude-plugin/marketplace.json" "$d/.claude-plugin/marketplace.json" cp "$REPO_ROOT/scripts/marketplace-rename-history.json" "$d/scripts/marketplace-rename-history.json" -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq 'del(.renames["automated-ai-engineer"]) - | .renames["replacement-old"] = "agentic-engineering"' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq 'del(.renames["automated-ai-engineer"]) + | .renames["replacement-old"] = "agentic-engineering"' "$m" > "$d/tmp" && mv "$d/tmp" "$m" jq 'del(.["automated-ai-engineer"]) | .["replacement-old"] = "agentic-engineering"' "$d/scripts/marketplace-rename-history.json" \ > "$d/tmp" && mv "$d/tmp" "$d/scripts/marketplace-rename-history.json" check_published_contract_fail "coordinated published rename replacement fails" "$d" d=$(fresh) -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq '.renames.alpha = "beta"' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq '.renames.alpha = "beta"' "$m" > "$d/tmp" && mv "$d/tmp" "$m" check_fail "current plugin cannot be a rename source" "rename sources must be retired kebab-case plugin names" "$d" d=$(fresh) -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq '.renames["dangling-plugin"] = "missing-plugin"' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq '.renames["dangling-plugin"] = "missing-plugin"' "$m" > "$d/tmp" && mv "$d/tmp" "$m" check_fail "dangling plugin rename target fails" "rename chains must terminate at a current plugin or null without cycles" "$d" d=$(fresh) -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq '.renames += {"old-alpha":"old-beta", "old-beta":"old-alpha"}' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq '.renames += {"old-alpha":"old-beta", "old-beta":"old-alpha"}' "$m" > "$d/tmp" && mv "$d/tmp" "$m" check_fail "cyclic plugin rename chain fails" "rename chains must terminate at a current plugin or null without cycles" "$d" # --- check 4: plugin.json completeness --- -d=$(fresh); jq '.name = "Bad_Name"' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq '.name = "Bad_Name"' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" # rename dir + manifest entry so only the kebab-case rule trips (keep lockstep intact) mv "$d/plugins/alpha" "$d/plugins/Bad_Name" -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq 'del(.renames["legacy-alpha"]) - | (.plugins[] | select(.name=="alpha")) |= (.name="Bad_Name" | .source="./plugins/Bad_Name")' \ - "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq 'del(.renames["legacy-alpha"]) + | (.plugins[] | select(.name=="alpha")) |= (.name="Bad_Name" | .source="./plugins/Bad_Name")' \ + "$m" > "$d/tmp" && mv "$d/tmp" "$m" jq 'del(.["legacy-alpha"])' "$d/scripts/marketplace-rename-history.json" \ > "$d/tmp" && mv "$d/tmp" "$d/scripts/marketplace-rename-history.json" check_fail "non-kebab plugin name fails" "must be kebab-case" "$d" -d=$(fresh); jq 'del(.description)' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq 'del(.description)' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "missing plugin.json description fails" "missing or empty 'description'" "$d" -d=$(fresh); jq 'del(.version)' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq 'del(.version)' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "missing plugin.json version fails" "missing or empty 'version'" "$d" -# Claude Desktop's remote marketplace service validates sourced plugins strictly. Unlike -# the local CLI, it requires .claude-plugin/plugin.json and rejects the whole marketplace -# when only the portable top-level plugin.json exists. Keep both manifests semantically -# identical so Claude and Copilot consume one plugin contract rather than drifting copies. +# Claude Desktop's remote marketplace service validates sourced plugins strictly and requires +# .claude-plugin/plugin.json, the one plugin manifest every supported tool reads. d=$(fresh); rm -f "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "missing strict Claude plugin manifest fails" \ - "plugins/alpha: every package requires its own regular canonical manifests" "$d" + "plugins/alpha: every package requires its own regular canonical manifest .claude-plugin/plugin.json" "$d" d=$(fresh); printf '%s\n' 'not json' > "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "malformed strict Claude plugin manifest fails" \ "Invalid plugins/alpha/.claude-plugin/plugin.json" "$d" -d=$(fresh); jq '.description = "Drifted Claude copy"' \ - "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" \ - && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" -check_fail "strict Claude plugin manifest drift fails" \ - "plugins/alpha/.claude-plugin/plugin.json differs from plugins/alpha/plugin.json" "$d" - # The bare-string 'skills'/'agents' form is exactly what breaks 'claude plugin install' # ('skills: Invalid input'); the guard must reject it and demand the array-or-omitted form. -d=$(fresh); jq '.skills = "skills/"' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq '.skills = "skills/"' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "bare-string 'skills' field fails" "'skills' must be an array of paths" "$d" -d=$(fresh); jq '.agents = "agents/"' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq '.agents = "agents/"' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "bare-string 'agents' field fails" "'agents' must be an array of paths" "$d" # The array form is accepted (auto-discovery still finds the on-disk skills either way). -d=$(fresh); jq '.skills = ["skills/example-skill"]' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq '.skills = ["skills/example-skill"]' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" check_pass "array 'skills' field passes" "$d" # A skills/ dir present but holding no /SKILL.md is a broken bundle. @@ -395,24 +342,20 @@ check_fail "plugin with no resource fails" "must declare at least one resource" # --- check 4: manifest <-> plugins lockstep --- d=$(fresh) -for m in "$d/.github/plugin/marketplace.json" "$d/.claude-plugin/marketplace.json"; do - jq '(.plugins[] | select(.name=="alpha")).source = "./wrong/alpha"' "$m" > "$d/tmp" && mv "$d/tmp" "$m" -done +m="$d/.claude-plugin/marketplace.json" +jq '(.plugins[] | select(.name=="alpha")).source = "./wrong/alpha"' "$m" > "$d/tmp" && mv "$d/tmp" "$m" check_fail "wrong manifest source fails" "must be './plugins/alpha'" "$d" d=$(fresh); rm -rf "$d/plugins/beta" -check_fail "manifest entry with no plugin dir fails" "has no plugins/beta/plugin.json on disk" "$d" +check_fail "manifest entry with no plugin dir fails" "has no plugins/beta/.claude-plugin/plugin.json on disk" "$d" -d=$(fresh); jq '.description = "Drifted"' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq '.description = "Drifted"' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "plugin.json description drift vs manifest fails" "description differs from manifest entry 'alpha'" "$d" -d=$(fresh); jq '.version = "2.0.0"' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq '.version = "2.0.0"' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "plugin.json version drift vs manifest fails" "version differs from manifest entry 'alpha'" "$d" -d=$(fresh); jq '.name = "alpha2"' "$d/plugins/alpha/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/plugin.json" -sync_claude_plugin_manifest "$d" alpha +d=$(fresh); jq '.name = "alpha2"' "$d/plugins/alpha/.claude-plugin/plugin.json" > "$d/tmp" && mv "$d/tmp" "$d/plugins/alpha/.claude-plugin/plugin.json" check_fail "plugin.json name drift vs manifest fails" "name differs from manifest entry 'alpha'" "$d" d=$(fresh); make_plugin "$d" gamma "Orphan plugin" "1.0.0" @@ -429,7 +372,7 @@ check_fail "a stale README cannot replace the missing catalogue" "docs/plugins.m d=$(fresh) # shellcheck disable=SC2016 printf '| [`gamma`](plugins/gamma/) | `example-skill` | Ghost plugin |\n' >> "$d/docs/plugins.md" -check_fail "README row for nonexistent plugin fails" "docs/plugins.md lists plugin 'gamma' with no plugins/gamma/plugin.json on disk" "$d" +check_fail "README row for nonexistent plugin fails" "docs/plugins.md lists plugin 'gamma' with no plugins/gamma/.claude-plugin/plugin.json on disk" "$d" # A README row whose plugins// exists but has no plugin.json (a stray dir the # orphan scan can't see) must be rejected, not silently accepted. @@ -438,7 +381,7 @@ mkdir -p "$d/plugins/gamma/skills/example-skill" printf 'Ghost skill.\n' > "$d/plugins/gamma/skills/example-skill/SKILL.md" # shellcheck disable=SC2016 printf '| [`gamma`](plugins/gamma/) | `example-skill` | Ghost plugin |\n' >> "$d/docs/plugins.md" -check_fail "README row for dir without plugin.json fails" "plugins/gamma: every package requires its own regular canonical manifests" "$d" +check_fail "README row for dir without plugin.json fails" "plugins/gamma: every package requires its own regular canonical manifest" "$d" # A stray skill directory must contain its own SKILL.md before catalogue parity. # Its absence cannot be hidden by adding the directory name to the catalogue. @@ -699,7 +642,6 @@ make_catalogued_plugin() { make_plugin "$root" "$name" "Canonical fixture" "1.0.0" jq --arg name "$name" '.plugins += [{name:$name,description:"Canonical fixture",version:"1.0.0",source:("./plugins/"+$name)}]' "$root/.claude-plugin/marketplace.json" > "$root/new" mv "$root/new" "$root/.claude-plugin/marketplace.json" - cp "$root/.claude-plugin/marketplace.json" "$root/.github/plugin/marketplace.json" # shellcheck disable=SC2016 # Literal catalogue markup. printf '| [`%s`](plugins/%s/) | `example-skill` | Canonical fixture |\n' "$name" "$name" >> "$root/docs/plugins.md" } @@ -1277,7 +1219,7 @@ check_fail "unsupported desired-state kind fails closed" \ d=$(fresh); make_desired_state "$d" typo check_fail "desired-state resource outside a manifested plugin fails" \ - "plugins/typo: every package requires its own regular canonical manifests" "$d" + "plugins/typo: every package requires its own regular canonical manifest .claude-plugin/plugin.json" "$d" d=$(fresh); make_catalogued_plugin "$d" agentic-engineering check_fail "missing canonical agentic desired-state resource fails" \ @@ -2308,14 +2250,14 @@ done # --- optional Codex manifest and the apps it offers --- # Codex reads .codex-plugin/plugin.json before .claude-plugin/plugin.json, so a Codex manifest must -# repeat the portable manifest exactly, add only Codex's component paths and listing, and offer +# repeat the canonical manifest exactly, add only Codex's component paths and listing, and offer # only optional apps. codex_fixture() { local d p d=$(fresh); p=$d/plugins/alpha mkdir -p "$p/.codex-plugin" jq '. + {skills: "./skills/", apps: "./.app.json", interface: {displayName: "Alpha"}}' \ - "$p/plugin.json" > "$p/.codex-plugin/plugin.json" + "$p/.claude-plugin/plugin.json" > "$p/.codex-plugin/plugin.json" printf '%s\n' '{"apps":{"mail":{"id":"connector_abc123","required":false},"people":{"id":"asdk_app_def456","required":false}}}' \ > "$p/.app.json" printf '%s' "$d" @@ -2326,13 +2268,23 @@ codex_edit() { # dir jq-filter file-relative-to-alpha check_pass "a Codex manifest offering optional apps passes" "$(codex_fixture)" +# The canonical side of the Codex comparison is a checked producer too: a failed or partial +# normalization never compares equal to the Codex manifest. +for output in empty partial; do + d=$(codex_fixture) + PATH="$WORK/normalization-bin:$PATH" REAL_JQ="$REAL_JQ" \ + JQ_FAILURE_PATTERN=plugins/alpha/.claude-plugin/plugin.json JQ_FAILURE_OUTPUT="$output" \ + check_fail "canonical manifest normalization failure with $output output fails the Codex comparison" \ + "Could not normalize plugins/alpha/.codex-plugin/plugin.json" "$d" +done + d=$(codex_fixture); codex_edit "$d" '.version = "9.9.9"' .codex-plugin/plugin.json check_fail "Codex manifest version drift fails" \ - "plugins/alpha/.codex-plugin/plugin.json differs from plugins/alpha/plugin.json" "$d" + "plugins/alpha/.codex-plugin/plugin.json differs from plugins/alpha/.claude-plugin/plugin.json" "$d" d=$(codex_fixture); codex_edit "$d" '.hooks = "./hooks.json"' .codex-plugin/plugin.json check_fail "a Codex manifest field beyond its component paths fails" \ - "plugins/alpha/.codex-plugin/plugin.json differs from plugins/alpha/plugin.json" "$d" + "plugins/alpha/.codex-plugin/plugin.json differs from plugins/alpha/.claude-plugin/plugin.json" "$d" d=$(codex_fixture); codex_edit "$d" 'del(.skills)' .codex-plugin/plugin.json check_fail "a Codex manifest that hides the bundled skills fails" \