Refactor: Extract CBT_Theme_Save service from rest_save_theme

[bph]

Summary

Lift the orchestration logic out of rest_save_theme() into a new
CBT_Theme_Save::run() static service, so the upcoming wp cbt save
CLI command (#830) can share the same code path. The REST endpoint
becomes a thin wrapper.

This is the first PR in the WP-CLI track tracked in #828.

Changes

• New: includes/create-theme/theme-save.php —
  CBT_Theme_Save::run( array $options ): true|WP_Error. Verbatim
  port of the four save branches (fonts, templates, styles, patterns)
  • theme cache invalidation.
• Modified: includes/class-create-block-theme-api.php —
  rest_save_theme() shrunk from 50 lines to 14: call run(),
  return WP_Error directly, otherwise wrap success in the existing
  WP_REST_Response shape.
• New: tests/test-theme-save.php — 13 PHPUnit cases.

Bug fixes that fall out of the refactor

The orchestration logic had two latent issues that get resolved by
the new normalize_flags() helper, which routes every flag through a
single ! empty() check:

1. processOnlySavedTemplates was previously dereferenced without an
   isset() guard, raising an Undefined index notice when
   saveTemplates was passed without it. The current Site Editor UI
   always sends both flags, so the notice was only reachable from
   non-JS callers — but the upcoming CLI is exactly that.
2. Flags were compared with strict true ===, rejecting 1,
   "true", "1". This is fine for a typed JS client and brittle
   for CLI and third-party REST callers.

Scope guarantees

No wire-level behavior change at the REST boundary:

• URL, HTTP method, permission callback unchanged.
• Response shape unchanged ({ status: 'SUCCESS', message: 'Theme Saved.' }).
• WP_Error from the patterns step is still returned as-is — the
  REST framework converts it to a JSON error response with the same
  status code as before.

The looser truthy semantics from the bug fix are isolated to the
/save endpoint. Sibling spots in the same file
(rest_create_variation, rest_reset_theme) keep their existing
strict-=== checks; those endpoints already had isset() guards
and never produced a notice. If we want consistency across the file,
that's worth a separate small PR.

Test plan

PHPUnit (added in this PR):

• test_run_with_empty_options_returns_true
• test_run_without_options_does_not_invoke_any_save_step
• test_save_templates_without_process_only_flag_does_not_warn —
  regression test for the processOnlySavedTemplates notice.
  Matcher narrowed to the key name so unrelated downstream notices
  do not fail it.
• test_truthy_save_fonts_values_trigger_persist (data provider:
  true, 1, "1", "true")
• test_falsy_save_fonts_values_skip_persist (data provider:
  false, 0, "", null)
• test_missing_save_fonts_key_skips_persist
• test_run_propagates_wp_error_from_patterns_step

Manual smoke (Site Editor → Save Changes panel) covering the four
branches and the WP_Error path:

• Save Fonts only — activated font moves into theme.
• Save Templates with Process Only Modified on — only
  modified templates written.
• Save Templates with Process Only Modified off — all
  templates written, no Undefined index notice in the PHP
  error log.
• Save Style Changes only — theme.json updated, user-side
  global styles cleared.
• Save Patterns with a name conflict — UI shows the
  pattern_already_exists snackbar error from WP_Error.

Cache invalidation (wp_get_theme()->cache_delete()) is not asserted
in PHPUnit; observing it would require mocking statics, which isn't
worth a new test framework just for one assertion.

Out of scope

• Any change to the underlying utility classes (CBT_Theme_Fonts,
  CBT_Theme_Templates, CBT_Theme_JSON, CBT_Theme_Patterns,
  CBT_Theme_Styles).
• The CLI command itself (Feature: Add wp cbt save CLI command #830).
• Extracting the other REST endpoints (variation/reset) — same
  pattern is there but the WP-CLI track only needs save and export.
• Promoting silent filesystem failures to WP_Error — separate
  concern, intentionally not broadened here.

Pre-existing bug noticed during testing (separate)

The strict error handler in the regression test surfaced an undefined
property access at theme-templates.php:233 ($template->media
read without a property check). Not introduced by this PR; worth a
small follow-up issue.

Refs #828
Closes #829

[Copilot]

Pull request overview

This PR extracts the “save theme” orchestration out of the REST handler into a reusable CBT_Theme_Save::run() service, enabling the upcoming WP-CLI wp cbt save command to share the same save implementation while keeping the REST endpoint behavior and response shape unchanged.

Changes:

• Introduces CBT_Theme_Save service to orchestrate fonts/templates/styles/patterns persistence with centralized flag normalization.
• Refactors rest_save_theme() into a thin wrapper around the new service.
• Adds PHPUnit coverage for flag normalization regressions and key save behaviors (including WP_Error propagation).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
includes/create-theme/theme-save.php	New service that contains the extracted save orchestration + flag normalization.
includes/class-create-block-theme-api.php	REST /save handler now delegates to CBT_Theme_Save::run() and preserves response shape.
tests/test-theme-save.php	New PHPUnit tests covering service behavior and regressions (undefined index + truthy flag handling).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bph]

@scruffian would appreciate a review here when you have a moment — this is the first refactor in the WP-CLI track (#828) and unblocks #830. No wire-level behavior change; the REST endpoint keeps the same URL, method, permission callback, and response shape.

Just pushed dbc140a addressing the Copilot review comment about the docblock — the previous wording implied a REST framework sanitize layer that doesn't actually exist for this route (/save has no args with sanitize_callback), so the docblock now states plainly that callers are responsible for sanitizing non-flag options.