@loopress/cli 0.24.0 → 0.25.0

package/dist/lib/snapshot-store.js

@@ -0,0 +1,133 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// How many snapshots `writeSnapshot` keeps per resource before pruning the oldest, so the
+// cache directory doesn't grow without bound across a project's lifetime.
+export const SNAPSHOT_RETENTION = 10;
+// `ResourceState` (a Map, for O(1) lookups during comparison) has no direct JSON
+// representation; snapshots round-trip through a plain object instead. Keys are sorted so two
+// snapshots of the same state serialize identically (stable diffs, deterministic tests).
+export function stateToRecord(state) {
+    return Object.fromEntries([...state].sort(([a], [b]) => a.localeCompare(b)));
+}
+export function recordToState(record) {
+    return new Map(Object.entries(record));
+}
+// Environment names are free text (whatever `lps project config` was given), not guaranteed to
+// be filesystem-safe path segments; anything outside a conservative safe set becomes '-'.
+function sanitizeForPath(name) {
+    return name.replaceAll(/[^\w-]/g, '-');
+}
+// Scoped by environment, not just resource: a project with multiple environments (staging,
+// production, ...) sharing one rootDir must never let a staging push's snapshot answer a
+// production rollback, or a staging push's retention prune a production restore point.
+function snapshotsDir(rootDir, resource, environment) {
+    return join(rootDir, '.loopress', 'snapshots', resource, sanitizeForPath(environment));
+}
+function snapshotPath(rootDir, resource, environment, id) {
+    return join(snapshotsDir(rootDir, resource, environment), `${id}.json`);
+}
+function isEnoent(error) {
+    return error.code === 'ENOENT';
+}
+function isEexist(error) {
+    return error.code === 'EEXIST';
+}
+// Snapshot ids are the millisecond timestamp they were written at: sortable, unique enough for
+// a single-machine CLI run, and directly usable as `--to <id>`.
+function isSnapshotFilename(name) {
+    return /^\d+\.json$/.test(name);
+}
+// Writes a snapshot for `resource`/`environment`, then prunes down to `retain` (oldest first),
+// so a project that pushes often never accumulates an unbounded `.loopress/snapshots/`
+// directory. Returns the new snapshot's id.
+//
+// Ids are millisecond timestamps; two pushes of the same resource/environment landing in the
+// same millisecond (only realistic from concurrent processes, never a single sequential CLI
+// run) would otherwise silently overwrite one restore point with another. `wx` (exclusive
+// create) turns that into a detected collision instead, retried against the next millisecond.
+export async function writeSnapshot(options) {
+    const { afterState, beforeState, environment, resource, retain = SNAPSHOT_RETENTION, rootDir } = options;
+    const dir = snapshotsDir(rootDir, resource, environment);
+    await mkdir(dir, { recursive: true });
+    const snapshot = {
+        afterState: stateToRecord(afterState),
+        beforeState: stateToRecord(beforeState),
+        createdAt: new Date().toISOString(),
+        environment,
+        resource,
+    };
+    const content = JSON.stringify(snapshot, null, 2) + '\n';
+    let id = Date.now();
+    for (;;) {
+        try {
+            await writeFile(join(dir, `${id}.json`), content, { flag: 'wx' });
+            break;
+        }
+        catch (error) {
+            if (!isEexist(error))
+                throw error;
+            id += 1;
+        }
+    }
+    await pruneSnapshots(rootDir, resource, environment, retain);
+    return String(id);
+}
+// Newest first. A missing snapshots directory (never pushed, or pruned to nothing) reads as
+// "no snapshots", not an error, the same ENOENT tolerance every resource-state provider gives
+// a never-pulled local directory.
+export async function listSnapshots(rootDir, resource, environment) {
+    const dir = snapshotsDir(rootDir, resource, environment);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+    const summaries = [];
+    const snapshotFiles = entries.filter((entry) => isSnapshotFilename(entry));
+    for (const entry of snapshotFiles) {
+        const id = entry.slice(0, -'.json'.length);
+        try {
+            const parsed = JSON.parse(await readFile(join(dir, entry), 'utf8'));
+            summaries.push({ createdAt: parsed.createdAt, environment: parsed.environment, id, resource });
+        }
+        catch {
+            // A corrupted or partially-written snapshot file (e.g. an interrupted write) is skipped
+            // rather than failing the whole listing; it stays on disk for a human to inspect.
+        }
+    }
+    return summaries.sort((a, b) => Number(b.id) - Number(a.id));
+}
+// `id` undefined reads the most recent snapshot for this environment (the common
+// `lps <resource> rollback` case). Throws a message ready to show the user directly: no
+// snapshots at all for this environment, or that specific id missing (renamed, deleted, or
+// written under a different resource/environment).
+export async function readSnapshot(rootDir, resource, environment, id) {
+    let targetId = id;
+    if (targetId === undefined) {
+        const [latest] = await listSnapshots(rootDir, resource, environment);
+        if (!latest) {
+            throw new Error(`No snapshots found for "${resource}" on "${environment}". A snapshot is written automatically by \`lps ${resource} push\`.`);
+        }
+        targetId = latest.id;
+    }
+    let raw;
+    try {
+        raw = await readFile(snapshotPath(rootDir, resource, environment, targetId), 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            throw new Error(`Snapshot "${targetId}" not found for "${resource}" on "${environment}". Run \`lps ${resource} rollback --list\` to see what's available.`, { cause: error });
+        }
+        throw error;
+    }
+    return { ...JSON.parse(raw), id: targetId };
+}
+export async function pruneSnapshots(rootDir, resource, environment, retain) {
+    const summaries = await listSnapshots(rootDir, resource, environment);
+    const stale = summaries.slice(retain);
+    await Promise.all(stale.map(async (summary) => rm(snapshotPath(rootDir, resource, environment, summary.id), { force: true })));
+}

package/dist/lib/validate-local.js

@@ -6,12 +6,13 @@ import { loadSnippets } from './load-snippets.js';
 import { readdirTolerant } from './readdir-tolerant.js';
 // Directories holding one JSON document per resource. Snippets (code file plus JSON sidecar)
 // and api routes (`.php`, not JSON) are checked separately.
-const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir'];
+const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir', 'menuDir'];
 const DEFAULT_DIR = {
     acfDir: 'acf',
     apiDir: 'api',
     formDir: 'forms',
     hooksDir: 'hooks',
+    menuDir: 'menus',
     seoDir: 'seo',
     snippetsDir: 'snippets',
 };

package/dist/lib/wp-authorize-flow.d.ts

@@ -18,5 +18,9 @@ export type AuthorizeResult = {
  *   5. The API callback returns an HTML page that POSTs a form with the
  *      Application Password to the local callback server.
  *   6. The local server extracts the credentials and resolves the promise.
+ *
+ * The `state` value is threaded through `callbackUrl` (the relay copies it verbatim into the
+ * form's POST target), so it comes back as a query param on the credential POST and
+ * `waitForLocalCallback` can match it before this handler runs.
  */
 export declare function authorizeWithBrowser(siteUrl: string, log: (message: string) => void): Promise<AuthorizeResult>;

package/dist/lib/wp-authorize-flow.js

@@ -15,13 +15,18 @@ import { renderResultPage, waitForLocalCallback } from './local-callback-server.
  *   5. The API callback returns an HTML page that POSTs a form with the
  *      Application Password to the local callback server.
  *   6. The local server extracts the credentials and resolves the promise.
+ *
+ * The `state` value is threaded through `callbackUrl` (the relay copies it verbatim into the
+ * form's POST target), so it comes back as a query param on the credential POST and
+ * `waitForLocalCallback` can match it before this handler runs.
  */
 export async function authorizeWithBrowser(siteUrl, log) {
     return waitForLocalCallback({
-        buildUrl(callbackBaseUrl) {
+        allowedOrigins: ['https://api.loopress.dev'],
+        buildUrl(callbackBaseUrl, state) {
             const relayUrl = 'https://api.loopress.dev/auth/wp-authorize';
             const params = new URLSearchParams({
-                callbackUrl: callbackBaseUrl,
+                callbackUrl: `${callbackBaseUrl}?state=${state}`,
                 wpUrl: siteUrl,
             });
             return `${relayUrl}?${params}`;
@@ -31,12 +36,9 @@ export async function authorizeWithBrowser(siteUrl, log) {
                 rejectWithPage(REJECTED_PAGE, new Error('Authorization rejected in WordPress.'));
                 return;
             }
-            // `||`, not `??`: an empty-string field counts as absent here, same as the `!password`
-            // check below, so falls through to the query-param fallback instead of stopping at "".
-            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-            const password = body.password || url.searchParams.get('password') || '';
-            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-            const userLogin = body.user_login || url.searchParams.get('user_login') || '';
+            // Credentials come from the relay's form POST only. Reading them from the query string
+            // would let them land in shell history, proxy logs and the browser address bar (F24).
+            const { password, user_login: userLogin } = body;
             if (!password || !userLogin) {
                 respondBadRequest('Missing password or user_login');
                 return;

package/dist/types/project-config.generated.d.ts

@@ -39,6 +39,14 @@ export interface LoopressProjectConfiguration {
      * Directory where explicitly tracked WordPress options (wp_options rows) are read from and written to, relative to rootDir. Only options added via `lps option add` live here, this is never the whole options table.
      */
     optionsDir?: string;
+    /**
+     * Directory where nav menus (one JSON file per menu, plus menu-locations.json for the active theme's menu locations) are read from and written to, relative to rootDir.
+     */
+    menuDir?: string;
+    /**
+     * Directory where the active block theme's Global Styles customizations (Site Editor > Styles: colors, typography, spacing) are read from and written to, relative to rootDir. Classic (non-block) themes are not supported.
+     */
+    themeStylesDir?: string;
     /**
      * Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config.
      */

package/dist/utils/acf-format.d.ts

@@ -1,4 +1,5 @@
 export declare const ACF_OBJECT_TYPES: readonly ["field-groups", "post-types", "taxonomies", "options-pages"];
 export type AcfObjectType = (typeof ACF_OBJECT_TYPES)[number];
 export declare function acfEndpoint(type: AcfObjectType): string;
+export declare function acfObjectEndpoint(type: AcfObjectType, key: string): string;
 export declare function getAcfKey(data: Record<string, unknown>): null | string;

package/dist/utils/acf-format.js

@@ -2,6 +2,12 @@ export const ACF_OBJECT_TYPES = ['field-groups', 'post-types', 'taxonomies', 'op
 export function acfEndpoint(type) {
     return `loopress/v1/acf/${type}`;
 }
+// GET/DELETE route for a single object by key, used by `acf push` to read the object's current
+// revision right before writing it (see acf/push.ts, #234). Create/update both go through
+// acfEndpoint() (a POST), the controller resolves create-vs-update server-side via `key`.
+export function acfObjectEndpoint(type, key) {
+    return `${acfEndpoint(type)}/${key}`;
+}
 // Deliberately loose: ACF's own export JSON is large, deeply nested, and versioned by ACF
 // itself (new settings appear across ACF releases). We only need `key` for filenames/identity;
 // everything else round-trips through pull/push untouched, so there's no generated type for it

package/dist/utils/form-format.d.ts

@@ -1,3 +1,7 @@
 export declare const FORM_ENDPOINT = "loopress/v1/forms";
+export declare function formEndpoint(id: number): string;
+export type RemoteForm = Record<string, unknown> & {
+    revision: string;
+};
 export declare function getFormId(data: Record<string, unknown>): null | number;
 export declare function getFormTitle(data: Record<string, unknown>): string;

package/dist/utils/form-format.js

@@ -1,11 +1,7 @@
 export const FORM_ENDPOINT = 'loopress/v1/forms';
-// Deliberately loose, same reasoning as getAcfKey in acf-format.ts: a form plugin's own data
-// format (WPForms today: fields, settings, notifications, confirmations, providers, meta; other
-// WordPress form plugins may be supported later, same shape as snippet-format.ts's Code
-// Snippets/WPCode split) is large, deeply nested, and versioned by whichever plugin release
-// wrote it. We only need `id` for filenames/identity and `settings.form_title` for display
-// (the field WPForms itself uses; a future provider may differ), everything else round-trips
-// through pull/push untouched.
+export function formEndpoint(id) {
+    return `${FORM_ENDPOINT}/${id}`;
+}
 export function getFormId(data) {
     const id = Number(data.id);
     return Number.isSafeInteger(id) && id > 0 ? id : null;

package/dist/utils/menu-format.d.ts

@@ -0,0 +1,24 @@
+export declare const MENU_ENDPOINT = "loopress/v1/menus";
+export declare const MENU_LOCATIONS_ENDPOINT = "loopress/v1/menu-locations";
+export declare function menuEndpoint(slug: string): string;
+export type MenuItem = {
+    children: MenuItem[];
+    classes: string[];
+    description: string;
+    object: null | string;
+    objectSlug: null | string;
+    target: string;
+    title: string;
+    type: 'custom' | 'post_type' | 'taxonomy';
+    url: null | string;
+    xfn: string;
+};
+export type Menu = {
+    items: MenuItem[];
+    name: string;
+    revision: string;
+    slug: string;
+    warnings: string[];
+};
+export type MenuLocations = Record<string, null | string>;
+export declare function getMenuSlug(data: Record<string, unknown>): null | string;

package/dist/utils/menu-format.js

@@ -0,0 +1,8 @@
+export const MENU_ENDPOINT = 'loopress/v1/menus';
+export const MENU_LOCATIONS_ENDPOINT = 'loopress/v1/menu-locations';
+export function menuEndpoint(slug) {
+    return `${MENU_ENDPOINT}/${encodeURIComponent(slug)}`;
+}
+export function getMenuSlug(data) {
+    return typeof data.slug === 'string' && data.slug.trim() !== '' ? data.slug : null;
+}

package/dist/utils/option-format.d.ts

@@ -1,7 +1,7 @@
 export declare const OPTIONS_ENDPOINT = "loopress/v1/options";
 export declare function optionEndpoint(name: string): string;
 export declare const RESERVED_OPTION_NAMES: readonly ["active_plugins", "stylesheet", "template"];
-export declare const READONLY_BY_DEFAULT_OPTION_NAMES: readonly ["siteurl", "home", "db_version", "cron", "rewrite_rules", "WPLANG"];
+export declare const READONLY_BY_DEFAULT_OPTION_NAMES: readonly ["siteurl", "home", "db_version", "initial_db_version", "cron", "rewrite_rules", "WPLANG", "default_role", "users_can_register", "uninstall_plugins", "mailserver_url", "mailserver_login", "mailserver_pass", "mailserver_port"];
 export type LocalOption = {
     autoload: string;
     name: string;
@@ -11,6 +11,7 @@ export type LocalOption = {
 export type RemoteOption = {
     autoload: string;
     name: string;
+    revision: string;
     value: unknown;
 };
 export type ListedOption = {

package/dist/utils/option-format.js

@@ -6,11 +6,29 @@ export function optionEndpoint(name) {
 // enforcement lives there). Checked here too so `option add` fails fast with a clear pointer to
 // the right command, instead of a round trip just to hit the server's 409.
 export const RESERVED_OPTION_NAMES = ['active_plugins', 'stylesheet', 'template'];
-// Options WordPress core owns or regenerates itself: legitimate to track for visibility (`diff`
-// still shows drift), but never something `push` should overwrite by default. siteurl/home in
+// Options WordPress core owns or regenerates itself, plus the ones OptionsService::
+// DENY_WRITE_NAMES refuses server-side (behaviour-changing core options: default_role,
+// users_can_register, mailserver_*, ...). Legitimate to track for visibility (`diff` still
+// shows drift), but never something `push` should overwrite by default. siteurl/home in
 // particular: pushing a value copied from another environment would repoint the target site's
-// own URLs, potentially locking out wp-admin.
-export const READONLY_BY_DEFAULT_OPTION_NAMES = ['siteurl', 'home', 'db_version', 'cron', 'rewrite_rules', 'WPLANG'];
+// own URLs, potentially locking out wp-admin. Flip `readonly` in the file to push one anyway;
+// for the server-denied names that then needs the `loopress_option_writable` filter too.
+export const READONLY_BY_DEFAULT_OPTION_NAMES = [
+    'siteurl',
+    'home',
+    'db_version',
+    'initial_db_version',
+    'cron',
+    'rewrite_rules',
+    'WPLANG',
+    'default_role',
+    'users_can_register',
+    'uninstall_plugins',
+    'mailserver_url',
+    'mailserver_login',
+    'mailserver_pass',
+    'mailserver_port',
+];
 export function isReservedOptionName(name) {
     return RESERVED_OPTION_NAMES.includes(name);
 }

package/dist/utils/plugin-sync.d.ts

@@ -9,9 +9,15 @@ export type SyncPayload = {
     intent: SyncIntent;
     lock: null | string;
 };
+export type LockDriftEntry = {
+    from: null | string;
+    name: string;
+    to: null | string;
+};
 export type SyncResponse = {
     composerJson: string;
     composerLock: string;
+    lockDrift?: LockDriftEntry[];
     message: string;
     output: string;
     removed: string[];

package/dist/utils/resource-dirs.d.ts

@@ -5,9 +5,11 @@ export declare const RESOURCE_DIR_DEFAULTS: {
     readonly apps: "apps";
     readonly form: "forms";
     readonly hooks: "hooks";
+    readonly menu: "menus";
     readonly options: "options";
     readonly seo: "seo";
     readonly snippets: "snippets";
+    readonly themeStyles: "theme";
 };
 export type ResourceDirKind = keyof typeof RESOURCE_DIR_DEFAULTS;
 export declare function resolveResourceDir(kind: ResourceDirKind, localConfig: LoopressLocalConfig, override?: string): string;

package/dist/utils/resource-dirs.js

@@ -7,9 +7,11 @@ export const RESOURCE_DIR_DEFAULTS = {
     apps: 'apps',
     form: 'forms',
     hooks: 'hooks',
+    menu: 'menus',
     options: 'options',
     seo: 'seo',
     snippets: 'snippets',
+    themeStyles: 'theme',
 };
 const CONFIG_KEY = {
     acf: 'acfDir',
@@ -17,9 +19,11 @@ const CONFIG_KEY = {
     apps: 'appsDir',
     form: 'formDir',
     hooks: 'hooksDir',
+    menu: 'menuDir',
     options: 'optionsDir',
     seo: 'seoDir',
     snippets: 'snippetsDir',
+    themeStyles: 'themeStylesDir',
 };
 // Resolves where a resource's files live: an explicit override wins, otherwise the
 // loopress.json `<kind>Dir` setting, otherwise the built-in default, all under `rootDir`.

package/dist/utils/seo-format.d.ts

@@ -3,11 +3,19 @@ export declare const SEO_SETTINGS_ENDPOINT = "loopress/v1/seo/settings";
 export declare const SEO_REDIRECTS_ENDPOINT = "loopress/v1/seo/redirects";
 export declare function seoRedirectEndpoint(id: number): string;
 export declare function seoPostMetaEndpoint(postType: string): string;
+export declare function seoPostMetaItemEndpoint(postType: string, slug: string): string;
 export type SeoPostMeta = {
     meta: Record<string, unknown>;
     slug: string;
     title: string;
 };
+export type RemoteSeoPostMeta = SeoPostMeta & {
+    revision: string;
+};
+export type RemoteSeoSettings = {
+    revision: string;
+    settings: Record<string, unknown>;
+};
 export type SeoRedirect = {
     createdAt: string | undefined;
     headerCode: number;

package/dist/utils/seo-format.js

@@ -9,6 +9,9 @@ export function seoRedirectEndpoint(id) {
 export function seoPostMetaEndpoint(postType) {
     return `loopress/v1/seo/post-meta/${postType}`;
 }
+export function seoPostMetaItemEndpoint(postType, slug) {
+    return `${seoPostMetaEndpoint(postType)}/${encodeURIComponent(slug)}`;
+}
 // The `<id>-<slug>.json` on-disk convention shared by `seo pull` and `seo push`.
 export function redirectFileBase(redirect) {
     return `${redirect.id}-${toSlug(redirect.urlTo, 'redirect')}`;

package/dist/utils/snippet-format.d.ts

@@ -11,6 +11,7 @@ export type NormalizedSnippet = {
     location: SnippetLocation;
     name: string;
     priority: number;
+    revision?: string;
     shortcodeAttributes: string[];
     tags: string[];
     type: SnippetType;

package/dist/utils/snippet-format.js

@@ -81,6 +81,7 @@ export function normalizeSnippet(data) {
         location: parseLocation(data.location) ?? defaultLocationForType(parseType(data.type) ?? 'php'),
         name: coerceString(data.name),
         priority: resolvePriority(data.priority),
+        revision: typeof data.revision === 'string' ? data.revision : undefined,
         shortcodeAttributes: Array.isArray(data.shortcodeAttributes) ? data.shortcodeAttributes.map(String) : [],
         tags: Array.isArray(data.tags) ? data.tags : [],
         type: parseType(data.type) ?? 'php',

package/dist/utils/theme-styles-format.d.ts

@@ -0,0 +1,26 @@
+import { type WpClient } from '../lib/wp-client.js';
+export declare const THEME_STYLES_FILE_SUFFIX = "-global-styles.json";
+export declare function themeStylesFileName(stylesheet: string): string;
+export declare function globalStylesEndpoint(id: number): string;
+export type WpThemeSupportInfo = {
+    _links?: Record<string, Array<{
+        href: string;
+    }>>;
+    status: 'active' | 'inactive';
+    stylesheet: string;
+    theme_supports?: Record<string, unknown>;
+};
+export declare function isBlockTheme(theme: Pick<WpThemeSupportInfo, 'theme_supports'>): boolean;
+export declare function getUserGlobalStylesId(theme: Pick<WpThemeSupportInfo, '_links'>): null | number;
+export declare function getActiveThemeGlobalStyles(wp: WpClient): Promise<{
+    id: number;
+    stylesheet: string;
+}>;
+export type GlobalStylesRecord = {
+    settings?: Record<string, unknown>;
+    styles?: Record<string, unknown>;
+};
+export declare function canonicalGlobalStyles(record: {
+    settings?: unknown;
+    styles?: unknown;
+}): Record<string, unknown>;

package/dist/utils/theme-styles-format.js

@@ -0,0 +1,55 @@
+// Global Styles are the user's customizations from the Site Editor's "Styles" screen (colors,
+// typography, spacing), stored by WordPress core in a `wp_global_styles` post, one per theme.
+// This is separate from the theme's own theme.json file, which lives in the theme's repo and is
+// out of scope here. Only block themes (Full Site Editing) have a Styles screen at all.
+export const THEME_STYLES_FILE_SUFFIX = '-global-styles.json';
+export function themeStylesFileName(stylesheet) {
+    return `${stylesheet}${THEME_STYLES_FILE_SUFFIX}`;
+}
+export function globalStylesEndpoint(id) {
+    return `wp/v2/global-styles/${id}`;
+}
+// WordPress core surfaces `wp_is_block_theme()` over the `wp/v2/themes` REST response as
+// `theme_supports['block-templates']` (see `_add_default_theme_supports()` in
+// wp-includes/theme.php): core adds that feature flag itself exactly when the theme has its own
+// block templates. No Loopress-side controller is needed to detect this.
+export function isBlockTheme(theme) {
+    return theme.theme_supports?.['block-templates'] === true;
+}
+// The `wp/v2/themes` list item links to its theme's editable `wp_global_styles` post under this
+// core-defined relation rather than exposing the id as a plain field (the same relation
+// @wordpress/e2e-test-utils-playwright's `getCurrentThemeGlobalStylesPostId()` reads). The href
+// itself varies with the site's permalink structure (`?rest_route=/wp/v2/global-styles/123` vs
+// `/wp-json/wp/v2/global-styles/123`), so the id is pulled out with a regex rather than assumed
+// to be the URL's last path segment.
+const USER_GLOBAL_STYLES_REL = 'wp:user-global-styles';
+export function getUserGlobalStylesId(theme) {
+    const href = theme._links?.[USER_GLOBAL_STYLES_REL]?.[0]?.href;
+    if (!href)
+        return null;
+    const match = /\/wp\/v2\/global-styles\/(\d+)/.exec(href);
+    return match ? Number(match[1]) : null;
+}
+// Resolves the active theme's stylesheet slug and the id of its editable Global Styles post in
+// one call, failing clearly (rather than with a raw REST error later) when the active theme
+// isn't a block theme: classic themes have no Styles screen and no `wp_global_styles` post at all.
+export async function getActiveThemeGlobalStyles(wp) {
+    const themes = await wp.get('wp/v2/themes');
+    const active = themes.find((theme) => theme.status === 'active');
+    if (!active)
+        throw new Error('Could not determine the active theme on WordPress.');
+    if (!isBlockTheme(active)) {
+        throw new Error(`Global Styles sync only supports block themes (Full Site Editing). The active theme "${active.stylesheet}" is a classic theme.`);
+    }
+    const id = getUserGlobalStylesId(active);
+    if (id === null) {
+        throw new Error(`Could not resolve the editable Global Styles post for "${active.stylesheet}". Requires an admin-capable account (edit_theme_options) on WordPress 5.9+.`);
+    }
+    return { id, stylesheet: active.stylesheet };
+}
+// The compared/stored value: `settings` and `styles` only. `id` and `_links` are WordPress
+// bookkeeping, not part of the tracked configuration (a fresh install resolves to a different
+// id for the same content), so they're dropped rather than becoming spurious drift.
+export function canonicalGlobalStyles(record) {
+    return { settings: record.settings ?? {}, styles: record.styles ?? {} };
+}