Closes #922: Add bulk-restore WP-CLI command

[Miraeld]

Note

This pull request was generated by the AI delivery pipeline (Claude Sonnet 4.6). Review carefully before merging.

Description

Fixes #922

Adds wp imagify restore [<contexts>...] WP-CLI subcommand. When a large number of images need to be restored (e.g. before switching compression level), the media library bulk-restore UI is impractical for operators. This command restores optimized media synchronously, printing per-context counts (restored / errors / total) and a final success or warning message.

Type of change

• New feature (non-breaking change which adds functionality).
• Bug fix (non-breaking change which fixes an issue).
• Enhancement (non-breaking change which improves an existing functionality).
• Breaking change (fix or feature that would cause existing functionality to not work as before).
• Sub-task of #(issue number)
• Chore
• Release

Detailed scenario

What was tested

Automated unit tests in Tests/Unit/classes/CLI/RestoreCommandTest.php cover:

• Default (no args) restores both library and custom-folders contexts and emits WP_CLI::success().
• library argument maps to internal wp context.
• custom-folders is passed through as-is.
• No eligible media → WP_CLI::warning() emitted, no success.
• Invalid context → WP_CLI::error() emitted with the bad value, command aborts.
• Partial errors (some images fail) → WP_CLI::warning() emitted instead of success.
• get_name() returns imagify restore.
• get_synopsis() has one optional repeating contexts positional arg.

32 unit tests, 81 assertions — all pass, 0 errors.

How to test

1. Boot a WP environment with Imagify active and some optimized images with backups.
2. wp imagify restore — restores both contexts, prints counts, emits success.
3. wp imagify restore library — restores WordPress media library only.
4. wp imagify restore custom-folders — restores custom-folders only.
5. With no eligible images: should emit WP_CLI::warning() instead of success.
6. wp imagify restore invalid — should print an error with invalid in the message.

Affected Features & Quality Assurance Scope

• WP-CLI integration (wp imagify root command)
• Bulk restore mechanism (Imagify\Bulk\Bulk::run_restore() — rewritten to synchronous)
• Imagify\Bulk\WP and Imagify\Bulk\CustomFolders — new get_optimized_media_ids() implementation
• Imagify\Bulk\Noop and NGG — explicit get_optimized_media_ids(): array returning []
• Imagify\Bulk\BulkInterface — get_optimized_media_ids(): array added to interface
• No changes to media library UI, AJAX endpoints, or compression settings
• ActionScheduler imagify_restore_media hook removed from Bulk::init()

Technical description

Documentation

docs/api/wp-cli.md updated with full command reference for wp imagify restore, including arguments, examples, behaviour, and get_optimized_media_ids() context implementations.

New dependencies

None.

Risks

Restore is a local filesystem operation (swap optimized file with backup). No API quota cost. No new async jobs or external calls introduced.

Mandatory Checklist

Code validation

• I validated all the Acceptance Criteria. If possible, provide screenshots or videos.
• I triggered all changed lines of code at least once without new errors/warnings/notices.
• I implemented built-in tests to cover the new/changed code.

Code style

• I wrote a self-explanatory code about what it does.
• I protected entry points against unexpected inputs.
• I did not introduce unnecessary complexity.
• Output messages (errors, notices, logs) are explicit enough for users to understand the issue and are actionnable.

Unticked items justification

Type of change: only "New feature" applies — this is a net-new WP-CLI subcommand with no existing behaviour changed or fixed.

Additional Checks

• In the case of complex code, I wrote comments to explain it.
• When possible, I prepared ways to observe the implemented system (logs, data, etc.)
• I added error handling logic when using functions that could throw errors (HTTP/API request, filesystem, etc.)

[codacy-production]

Up to standards ✅

🟢 Issues 1 medium

Results:
1 new issue

Category	Results
UnusedCode	1 medium

View in Codacy

🟢 Metrics 32 complexity · 0 duplication

Metric	Results
Complexity	32
Duplication	0

View in Codacy

🟢 Coverage 52.44% diff coverage

Metric	Results
Coverage variation	Report missing for 9b42eaa1
Diff coverage	✅ 52.44% diff coverage (50.00%)

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (9b42eaa)	Report Missing	Report Missing	Report Missing
Head commit (260ac4a)	18639	284	1.52%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#1087)	164	86	52.44%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

¹ Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct.

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[Miraeld]