Skip to content

feat: block-plugin-scaffold - reusable engine, preview and approval (BPS-12 phase 2) - #67

Merged
krugazul merged 1 commit into
feat/bps-12-contractfrom
feat/bps-12-engine-boundary
Nov 6, 2026
Merged

krugazul merged 1 commit into
feat/bps-12-contractfrom
feat/bps-12-engine-boundary

Conversation

@krugazul

@krugazul krugazul commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Feature Pull Request

Phase 2 of 4 for BPS-12, stacked on #66 (feat/bps-12-contract). Review #66 first; this PR's diff is only phase 2.

Linked issues

Part of #65

What this changes

Reusable generator engine (T2), scripts/generate-plugin.js

  • generatePlugin(config, options) takes outputDir (the exact folder), outputBaseDir, force, now, logFile and output. generatePlugin(config, true) still means template mode.
  • It reads nothing from process.argv and never exits the process.
  • It writes diagnostics to standard error, not standard output, which an MCP server needs for protocol messages.
  • Each call has its own log, written when the call ends. Before, the first call's log state was reused by every later call.
  • Importing the module no longer creates logs/ or registers exit and Ctrl+C handlers.
  • The CLI now does the CLI-only work: console output, --output-dir, --force, --in-place, exit handling and the "next steps" text.
  • The .pot creation date and log timestamps come from the injected clock, so output can be compared exactly.
  • generate-plugin.agent.js passes --force through, because the generator no longer reads it from the command line.

Preview and approval (T3), 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 destination files it will leave alone;
    • binds a SHA-256 approval hash to the configuration, destination and staged files.

    An approval is refused when it doesn't match, the preview expired (30 minutes) or was replaced, or the destination changed since the preview.

  • config.js validates with the generator's own rules and reports whether each value was supplied, derived or defaulted.

  • errors.js holds the contract's error codes.

The contract's destination rules and status are updated to match.

Verification

Following the agreed approach, everything was checked by generating plugins. The scaffold's own test suite was not run.

  • CLI output is unchanged: both fixtures generate the same files as before this change, apart from the .pot creation date.
  • Library parity: two library runs with a fixed clock produce identical output, which matches the CLI's apart from that date.
  • check:generation passes for both fixtures (default, functional-only): npm ci, build, all lints, unit tests, composer validate/install/lint/PHPStan/PHPUnit.
  • 62 scripted checks pass, covering:
    • importing the module writes nothing and registers no handlers;
    • standard output stays empty during generation and preview;
    • each run's log is separate;
    • create, overwrite and unchanged actions;
    • conflicts for a folder where a file is planned, a symbolic link in the path, and the link itself;
    • preserved files and .git detection, with the destination untouched by preview;
    • approval refused for a wrong hash, approved: false or "yes", an unknown preview, a replaced preview and an expired preview;
    • stale previews for an edited planned file, a new file at a planned path, and a destination replaced by a link, while editing an unrelated file does not make a preview stale;
    • invalid configuration and staging failures;
    • 15 refused and 4 allowed destinations, including ~/Studio/.../wp-content/plugins/tsp.

ESLint ignores scripts/ in this repository, so the new files are checked by Prettier only. generate-plugin.js was not Prettier-formatted before this change either; I left its formatting alone so the diff stays readable.

Changelog

Added

  • Preview and approval for local MCP generation (BPS-12, scripts/mcp/).

Changed

  • generatePlugin() can be called repeatedly from one process. It takes options, reads nothing from process.argv, writes diagnostics to standard error and keeps a separate log per call. The CLI's output and generated files are unchanged.

Checklist (Global DoD / PR)

  • All AC met and demonstrated (for this phase: T2 and T3)
  • Tests added/updated: verified by generating plugins instead, as agreed
  • Accessibility checklist: not applicable, no user interface
  • Docs/readme/changelog updated
  • Security checklist: untrusted destination paths validated (absolute paths only, no .., no system or home folders, no links); approval bound by hash
  • Code/design reviews approved
  • CI green

🤖 Generated with Claude Code

Phase 2 of BPS-12 (T2 and T3).

Engine boundary (scripts/generate-plugin.js):
- generatePlugin(config, options) takes outputDir, outputBaseDir, force,
  now, logFile and output; the boolean form still means template mode.
- It no longer reads process.argv, never exits the process, writes
  diagnostics to standard error, and keeps one log run per call, written
  when the call ends, so repeated calls never share log state.
- Importing the module creates nothing and registers no process
  handlers; the CLI sets console output, exit and Ctrl+C handling, reads
  --output-dir, --force and --in-place, and prints the next steps.
- The .pot creation date and log timestamps come from the injected clock.
- generate-plugin.agent.js passes --force through explicitly.

Preview and approval (scripts/mcp/):
- preview.js resolves and checks the destination, generates into a
  private staging folder, classifies every staged path as create,
  overwrite, unchanged or conflict (Git paths, links in the path, type
  clashes), summarises preserved files, and binds a SHA-256 approval hash
  to the configuration, destination and staged files. Approvals are
  refused when they do not match, the preview expired or was replaced,
  or the destination changed since.
- config.js validates with the generator's own rules and reports each
  value's source; errors.js holds the contract's error codes.

Verified by generating plugins only: CLI output matches the previous
generator apart from the .pot date, two library runs with a fixed clock
are identical, standard output stays empty, and check:generation passes
for both fixtures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@linear-code

linear-code Bot commented Nov 6, 2026

Copy link
Copy Markdown

BPS-12

@coderabbitai

coderabbitai Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 17 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Central YAML; Path: .coderabbit.yaml
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 18ce443e-c77d-49f7-a899-b7ccb8cec47f
Commits

Reviewing files that changed from the base of the PR and between 5f75e09 and 7bc1d74.

Files selected for processing: 7

  • CHANGELOG.md
  • docs/MCP-PLUGIN-GENERATION.md
  • scripts/agents/generate-plugin.agent.js
  • scripts/generate-plugin.js
  • scripts/mcp/config.js
  • scripts/mcp/errors.js
  • scripts/mcp/preview.js
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@krugazul
krugazul marked this pull request as ready for review November 6, 2026 09:36
@krugazul
krugazul added this pull request to stack #71 November 6, 2026 10:18
@krugazul
krugazul merged commit 6a4eb30 into develop Nov 6, 2026
6 of 20 checks passed
@krugazul
krugazul deleted the feat/bps-12-engine-boundary branch November 6, 2026 12:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant