Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- Local MCP server for plugin generation (BPS-12, `scripts/mcp/server.js`, `npm run mcp:server`): `discover`, `validate_config`, `preview` and `generate` over stdio for Claude Desktop and Claude Code, built on the official `@modelcontextprotocol/sdk` (new dev dependency, with `zod`). `preview` returns a compact file list by default (every overwrite and conflict, new files counted by folder) and the full list with `detail: "full"`. Verified with Claude Code and Claude Desktop on macOS.
- Safe merge for local MCP generation (BPS-12, `scripts/mcp/merge.js`): after an approval matches its preview, `generate` writes only the planned paths into the destination. It never deletes, never touches Git paths or unrelated files, re-checks each path just before writing it, writes each file to a temporary name and renames it into place, backs up every file before overwriting it, and records each step in a journal. A failure part-way returns `PARTIAL_WRITE` with what was and was not written; previewing and generating again completes the rest.
- Preview and approval for local MCP generation (BPS-12, `scripts/mcp/`): `preview.js` checks the destination against the contract's rules, generates into a private staging folder, marks every planned path `create`, `overwrite`, `unchanged` or `conflict` (Git paths, symbolic links in the path and type clashes are conflicts), counts the files it leaves alone, and binds an approval hash to the configuration, destination and staged files. An approval is refused if it does not match, the preview expired (30 minutes) or was replaced, or the destination changed since. `config.js` validates with the generator's own rules and reports where each value came from.
- Vitest tests for the local MCP tooling (BPS-12): `npm run test:mcp` runs `scripts/mcp/__tests__/` with `@vitest/coverage-v8` (new dev dependency) and fails below 80% coverage. The tests generate real plugins into temporary folders and cover the engine boundary, preview, approval, destination rules, the safe merge and the server over in-memory and stdio transports.
- Local MCP server for plugin generation (BPS-12, `scripts/mcp/server.mts`, `npm run mcp:server`): `discover`, `validate_config`, `preview` and `generate` over stdio for Claude Desktop and Claude Code, built on the official `@modelcontextprotocol/sdk` (new dev dependency, with `zod`). `preview` returns a compact file list by default (every overwrite and conflict, new files counted by folder) and the full list with `detail: "full"`. Verified with Claude Code and Claude Desktop on macOS.
- Safe merge for local MCP generation (BPS-12, `scripts/mcp/merge.mts`): after an approval matches its preview, `generate` writes only the planned paths into the destination. It never deletes, never touches Git paths or unrelated files, re-checks each path just before writing it, writes each file to a temporary name and renames it into place, backs up every file before overwriting it, and records each step in a journal. A failure part-way returns `PARTIAL_WRITE` with what was and was not written; previewing and generating again completes the rest.
- Preview and approval for local MCP generation (BPS-12, `scripts/mcp/`): `preview.mts` checks the destination against the contract's rules, generates into a private staging folder, marks every planned path `create`, `overwrite`, `unchanged` or `conflict` (Git paths, symbolic links in the path and type clashes are conflicts), counts the files it leaves alone, and binds an approval hash to the configuration, destination and staged files. An approval is refused if it does not match, the preview expired (30 minutes) or was replaced, or the destination changed since. `config.js` validates with the generator's own rules and reports where each value came from.
- `docs/MCP-PLUGIN-GENERATION.md` (BPS-12): the contract for generating plugins through a local MCP server in Claude Desktop and Claude Code. It covers responsibilities, transport, client setup, destination rules, the four operations, approval binding, merge rules, errors, recovery, the supported configuration where the schema, generator and validator disagree, and the WordPress and Figma skills.
- Generated plugins get `package-lock.json` and `composer.lock` (BPS-10), written from the lockfiles proven in `lightspeedwp/ls-test` (`scripts/toolchain/standard-toolchain.package-lock.json` and `standard-toolchain.composer.lock`) with the plugin's name, version and Composer `content-hash`; for ls-test they are byte-identical to its own. `npm run toolchain:lockfiles` resolves them again after a toolchain change. `check:generation` installs with `npm ci` and runs `composer validate`, so a lockfile that no longer matches fails, then `composer install`, PHPCS, PHPStan and PHPUnit in each generated plugin; the CI job sets up PHP 8.4.
- Generated plugins get `guidelines/` (BPS-10, adapted from ThisOneTimeOnAcidCom): CSS architecture, an accessibility checklist, the testing strategy, and prompt and report guides. `compare-toolchain.js` compares `guidelines/`.
Expand Down Expand Up @@ -75,6 +76,7 @@ All components use mustache placeholders and follow WordPress accessibility and

### Changed

- The local MCP tooling in `scripts/mcp/` is TypeScript (`.mts`, run directly by Node 24.18+ with no build step), following the repository rule for agent tooling. Its behaviour is unchanged apart from one fix: a destination under a file now gives `UNSAFE_DESTINATION` instead of an internal error. Claude Desktop and Claude Code configurations must point at `scripts/mcp/server.mts`.
- `generatePlugin()` can be called repeatedly from one process (BPS-12). It takes options (`outputDir` for the exact folder, `outputBaseDir`, `force`, `now`, `logFile`, `output`; `generatePlugin(config, true)` still means template mode), reads nothing from `process.argv`, writes diagnostics to standard error instead of standard output, and keeps a separate log per call, written when the call ends. Importing the module no longer creates `logs/` or registers exit and Ctrl+C handlers; only the CLI does. The CLI's output and generated files are unchanged, and `generate-plugin.agent.js` passes `--force` through.
- The generated `AGENTS.md` and `CLAUDE.md` describe the full branch rule, `{type}/{scope}-{title}`, instead of only the type prefix.
- `npm run format` in generated plugins writes YAML with two spaces, as `.editorconfig` asks, instead of four, and a new `.prettierignore` leaves `.specify/`, the generator's `*-config.json`, the centrally managed `dependency-automation.yml` and generated folders alone. `styles/blocks/button-primary.json` is formatted to match, and `compare-toolchain.js` compares `.prettierignore`.
Expand Down Expand Up @@ -111,6 +113,7 @@ All components use mustache placeholders and follow WordPress accessibility and

### Fixed

- Local MCP generation (BPS-12, CodeRabbit review on #66): on a fresh checkout, the default destination works: `generate` creates the Git-ignored `generated-plugins/` folder (that folder only, and only for the default; `preview` reports `createsParentFolder: true`). `preview` compares each file's executable bit as well as its contents, so a script that lost its bit is `overwrite` and gets it back. The contract now says a planned link already pointing at the same target is `unchanged`, and that legacy `cpt_slug` and `name_singular` are rejected with `content_model: "none"`.
- The tag scanner (`scripts/utils/scan.js`) reads mustache dotted filter tags such as `{{upper.namespace}}` as the variable they filter, and skips GitHub Actions `${{ ... }}` expressions. Counts use the same grammar, so `{{ upper.slug }}` counts too, and `.mustacheignore` skips `.specify/workflows/` and `.gemini/commands/`, which the generator copies without rendering. `scripts/mustache-variables-registry.json` is regenerated: it lists the tags templates use now, without the old `{{name|filter}}` forms or the theme tags no file uses.
- Collection blocks in generated plugins render: `block.json` named a PHP function as `render`, which WordPress reads as a file path, so the blocks output nothing. It now points at `file:./render.php`, which echoes the documented render function, as the slider block does (BPS-10).
- Generated block patterns name the plugin in their header comment instead of "ExamplePlugin", and their array arrows are aligned, so PHPCS passes on plugins with post types (BPS-10).
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,6 @@
- Skills in `.claude/skills/` are symlinks to `.agents/skills/` (see `.agents/README.md`). The WordPress skills are vendored from WordPress/agent-skills at the commit in `.agents/skills/VENDORED.md`; refresh them with `npm run sync:agent-skills`, never by editing them.
- `plugin-template/` is the source of generated plugins and has its own `.claude/`, `.agents/` and `CLAUDE.md`. `scripts/agent-skills.json` updates both, and `scripts/generate-plugin.js` copies the vendored skills without rendering them.
- Agent tooling in `scripts/` is TypeScript. `scripts/sync-agent-skills.ts` runs on Node 24.18+ directly (type stripping), with Jest tests in `scripts/__tests__/` (`npm run test:agent-skills`, 80% coverage enforced). Do not add shell scripts.
- The local MCP generation tooling in `scripts/mcp/` is TypeScript too (`.mts`, ES modules, run directly by Node). Its tests use Vitest, not Jest: `npm run test:mcp` (80% coverage enforced). See `docs/MCP-PLUGIN-GENERATION.md`.
- Put machine-specific settings in `.claude/settings.local.json`, which Git ignores.
- `.claude/settings.json` enables the `ls-claude-agents-router` plugin from the `lightspeedwp` marketplace, which routes the organisation agents in `lightspeedwp/.github` into Claude Code. Claude Code offers to install it when you trust this folder. It needs `~/.github` cloned (on `develop`) and Git access to the private repository (`gh auth login`, then `gh auth setup-git`).
Loading
Loading