@loopress/cli 0.22.0 → 0.24.0

package/dist/lib/resource-state.js

@@ -0,0 +1,361 @@
+import { readFile } from 'node:fs/promises';
+import { basename, join, relative, sep } from 'node:path';
+import { ACF_OBJECT_TYPES, acfEndpoint, getAcfKey } from '../utils/acf-format.js';
+import { FORM_ENDPOINT, getFormId } from '../utils/form-format.js';
+import { optionEndpoint, parseLocalOption } from '../utils/option-format.js';
+import { DEFAULT_POST_TYPES, SEO_REDIRECTS_ENDPOINT, SEO_SETTINGS_ENDPOINT, seoPostMetaEndpoint, } from '../utils/seo-format.js';
+import { normalizeSnippet, SNIPPETS_ENDPOINT, stripPhpOpeningTag } from '../utils/snippet-format.js';
+import { loadFiles } from './load-files.js';
+import { loadSnippets } from './load-snippets.js';
+import { isApplicative404, isNotFoundError } from './wp-client.js';
+function readJson(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('not a JSON object');
+    }
+    return parsed;
+}
+// Removes top-level keys that the server rewrites without the tracked configuration itself
+// changing (save timestamps, hit counters), so a `diff` between two independently-configured
+// environments reports real differences only. Top-level only: a nested user field that happens
+// to share a name is never touched.
+function omit(object, keys) {
+    return Object.fromEntries(Object.entries(object).filter(([key]) => !keys.includes(key)));
+}
+// ACF's export JSON carries `modified` (a unix timestamp bumped on every save in wp-admin).
+const ACF_VOLATILE_KEYS = ['modified'];
+// A WPForms form is a WP post; `modified`/`modified_gmt` move on every edit.
+const FORM_VOLATILE_KEYS = ['modified', 'modified_gmt'];
+// A RankMath redirect's `hits` is a live visit counter.
+const REDIRECT_VOLATILE_KEYS = ['hits'];
+// ---- snippets -------------------------------------------------------------------------------
+// `description` is dropped: `snippet push` overwrites it with "Imported from <path>" on every
+// push and `loadSnippets` never reads it back, so it is not part of the synced state. `id`
+// becomes the map key. `code` has its leading `<?php` stripped on both sides: `snippet pull`
+// re-adds it to PHP files for editor friendliness, WordPress stores only the body.
+function canonicalSnippet(snippet) {
+    return {
+        active: snippet.active,
+        code: stripPhpOpeningTag(snippet.code),
+        insertMethod: snippet.insertMethod,
+        location: snippet.location,
+        name: snippet.name,
+        priority: snippet.priority,
+        shortcodeAttributes: [...snippet.shortcodeAttributes],
+        tags: [...snippet.tags],
+        type: snippet.type,
+    };
+}
+const snippetProvider = {
+    dirKind: 'snippets',
+    async local(dir) {
+        const state = new Map();
+        let snippets;
+        try {
+            snippets = await loadSnippets(dir);
+        }
+        catch (error) {
+            // A directory that was never created is "nothing tracked locally", the same tolerance
+            // loadFiles/readdirTolerant already have; loadSnippets wraps the ENOENT in its own Error.
+            if (error.cause?.code === 'ENOENT')
+                return state;
+            throw error;
+        }
+        for (const snippet of snippets) {
+            const id = snippet.id === undefined ? `local:${basename(snippet.path)}` : String(snippet.id);
+            state.set(id, canonicalSnippet(snippet));
+        }
+        return state;
+    },
+    async remote(wp) {
+        const raw = await wp.get(SNIPPETS_ENDPOINT);
+        const state = new Map();
+        for (const item of raw) {
+            const snippet = normalizeSnippet(item);
+            state.set(String(snippet.id), canonicalSnippet(snippet));
+        }
+        return state;
+    },
+    resource: 'snippet',
+    title: 'Snippets',
+};
+// ---- forms -------------------------------------------------------------------------------
+// The form plugin's own JSON (WPForms today) round-trips untouched through pull/push, so
+// (minus save timestamps) the whole object is the compared value, same "deliberately loose"
+// stance as form-format.ts.
+const formProvider = {
+    dirKind: 'form',
+    async local(dir, onWarn) {
+        const entries = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse: (raw, filePath) => ({ file: basename(filePath, '.json'), value: readJson(raw) }),
+        });
+        const state = new Map();
+        for (const { file, value } of entries) {
+            const formId = getFormId(value);
+            state.set(formId === null ? `local:${file}` : String(formId), omit(value, FORM_VOLATILE_KEYS));
+        }
+        return state;
+    },
+    async remote(wp) {
+        const raw = await wp.get(FORM_ENDPOINT);
+        const state = new Map();
+        for (const form of raw) {
+            const formId = getFormId(form);
+            if (formId !== null)
+                state.set(String(formId), omit(form, FORM_VOLATILE_KEYS));
+        }
+        return state;
+    },
+    resource: 'form',
+    title: 'Forms',
+};
+// ---- ACF --------------------------------------------------------------------------------
+// ACF's export JSON is large, deeply nested, and versioned by ACF itself; `key` is the stable
+// identity and the whole object (minus the `modified` timestamp) round-trips untouched, so it
+// is all compared. Ids are namespaced by object type (`field-groups/group_x`) since keys are
+// only unique within a type.
+const acfProvider = {
+    dirKind: 'acf',
+    async local(dir, onWarn) {
+        const state = new Map();
+        for (const type of ACF_OBJECT_TYPES) {
+            const objects = await loadFiles(join(dir, type), {
+                extension: '.json',
+                onSkip: onWarn,
+                parse: readJson,
+            });
+            for (const object of objects) {
+                const key = getAcfKey(object);
+                if (key !== null)
+                    state.set(`${type}/${key}`, omit(object, ACF_VOLATILE_KEYS));
+            }
+        }
+        return state;
+    },
+    async remote(wp) {
+        const state = new Map();
+        for (const type of ACF_OBJECT_TYPES) {
+            const raw = await wp.get(acfEndpoint(type));
+            for (const object of raw) {
+                const key = getAcfKey(object);
+                if (key !== null)
+                    state.set(`${type}/${key}`, omit(object, ACF_VOLATILE_KEYS));
+            }
+        }
+        return state;
+    },
+    resource: 'acf',
+    title: 'ACF',
+};
+// ---- PHP file directories (API routes, hooks) -----------------------------------------
+// api/ and hooks/ are both just a recursive directory of PHP files whose text is compared
+// verbatim (line diff on change), no server-side normalization to undo. Only the directory
+// kind, the endpoint and the labels differ.
+function phpFilesProvider(spec) {
+    const toState = (files) => {
+        const state = new Map();
+        for (const file of files)
+            state.set(file.filename, file.content);
+        return state;
+    };
+    return {
+        dirKind: spec.dirKind,
+        async local(dir, onWarn) {
+            return toState(await loadFiles(dir, {
+                extension: '.php',
+                onSkip: onWarn,
+                parse: (raw, filePath) => ({
+                    content: raw,
+                    filename: relative(dir, filePath).slice(0, -'.php'.length).split(sep).join('/'),
+                }),
+                recursive: true,
+            }));
+        },
+        async remote(wp) {
+            return toState(await wp.get(spec.endpoint));
+        },
+        resource: spec.resource,
+        title: spec.title,
+    };
+}
+const apiProvider = phpFilesProvider({
+    dirKind: 'api',
+    endpoint: 'loopress/v1/api-files',
+    resource: 'api',
+    title: 'API routes',
+});
+const hookProvider = phpFilesProvider({
+    dirKind: 'hooks',
+    endpoint: 'loopress/v1/hook-files',
+    resource: 'hook',
+    title: 'Hooks',
+});
+// ---- SEO --------------------------------------------------------------------------------
+function canonicalRedirect(redirect) {
+    return omit(redirect, REDIRECT_VOLATILE_KEYS);
+}
+const seoProvider = {
+    dirKind: 'seo',
+    async local(dir, onWarn) {
+        const state = new Map();
+        // The provider settings blob (Yoast / RankMath) is compared whole. If a real payload turns
+        // out to carry install-specific noise (a plugin version, a license hash), add those keys
+        // to an omit() list here, the e2e round-trip is what will surface them.
+        const settingsPath = join(dir, 'settings.json');
+        try {
+            const settings = readJson(await readFile(settingsPath, 'utf8'));
+            state.set('settings', settings);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                onWarn(`Skipping "${settingsPath}": ${error.message}`);
+            }
+        }
+        for (const postType of DEFAULT_POST_TYPES) {
+            const metaDir = join(dir, 'post-meta', postType);
+            const entries = await loadFiles(metaDir, {
+                extension: '.json',
+                onSkip: onWarn,
+                parse: (raw, filePath) => ({ file: basename(filePath, '.json'), value: readJson(raw) }),
+            });
+            for (const { file, value } of entries) {
+                const slug = typeof value.slug === 'string' && value.slug !== '' ? value.slug : `local:${file}`;
+                state.set(`post-meta/${postType}/${slug}`, value);
+            }
+        }
+        const redirects = await loadFiles(join(dir, 'redirects'), {
+            extension: '.json',
+            onSkip: onWarn,
+            parse: readJson,
+        });
+        for (const redirect of redirects) {
+            const id = Number(redirect.id);
+            if (Number.isSafeInteger(id) && id > 0)
+                state.set(`redirects/${id}`, canonicalRedirect(redirect));
+        }
+        return state;
+    },
+    async remote(wp, onWarn) {
+        const state = new Map();
+        const settings = await wp.get(SEO_SETTINGS_ENDPOINT);
+        state.set('settings', settings);
+        for (const postType of DEFAULT_POST_TYPES) {
+            const posts = await wp.get(seoPostMetaEndpoint(postType));
+            for (const post of posts)
+                state.set(`post-meta/${postType}/${post.slug}`, post);
+        }
+        // Redirects are a RankMath-only feature; on Yoast the endpoint 404s, same graceful skip
+        // as `seo pull`.
+        try {
+            const redirects = await wp.get(SEO_REDIRECTS_ENDPOINT);
+            for (const redirect of redirects) {
+                state.set(`redirects/${redirect.id}`, canonicalRedirect(redirect));
+            }
+        }
+        catch (error) {
+            if (!isNotFoundError(error))
+                throw error;
+            onWarn(`Skipping redirects: not supported by the active SEO plugin`);
+        }
+        return state;
+    },
+    resource: 'seo',
+    title: 'SEO',
+};
+// ---- Options ------------------------------------------------------------------------------
+// Unlike every provider above, remote() has no "everything" endpoint to read: GET /options only
+// lists names, never values (by design, see OptionsController), so both sides compare exactly
+// the locally tracked set, read from `dir` on the remote side too (see ResourceStateProvider's
+// docstring). `readonly` is a local policy flag with no WordPress counterpart, left out of both
+// sides so it can never itself show up as drift.
+const optionsProvider = {
+    dirKind: 'options',
+    async local(dir, onWarn) {
+        const entries = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse(raw) {
+                const option = parseLocalOption(raw);
+                return { autoload: option.autoload, name: option.name, value: option.value };
+            },
+        });
+        const state = new Map();
+        for (const { autoload, name, value } of entries)
+            state.set(name, { autoload, value });
+        return state;
+    },
+    async remote(wp, onWarn, dir) {
+        const tracked = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse: (raw) => parseLocalOption(raw).name,
+        });
+        const state = new Map();
+        for (const name of tracked) {
+            try {
+                const option = await wp.get(optionEndpoint(name));
+                state.set(name, { autoload: option.autoload, value: option.value });
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+                // Absent on this environment (never pushed here, or deleted there): left out of the
+                // map, which reads as "removed" on this side, exactly the right signal.
+            }
+        }
+        return state;
+    },
+    resource: 'option',
+    title: 'Options',
+};
+export const RESOURCE_STATE_PROVIDERS = [
+    snippetProvider,
+    formProvider,
+    acfProvider,
+    apiProvider,
+    hookProvider,
+    seoProvider,
+    optionsProvider,
+];
+export function getResourceStateProvider(resource) {
+    const provider = RESOURCE_STATE_PROVIDERS.find((candidate) => candidate.resource === resource);
+    if (!provider)
+        throw new Error(`No resource-state provider for "${resource}"`);
+    return provider;
+}
+// ---- Composer ---------------------------------------------------------------------------
+// Composer isn't a directory of items but two files at the project root, so it sits outside
+// RESOURCE_STATE_PROVIDERS. The compared value is each file's text.
+const COMPOSER_JSON_ENDPOINT = 'loopress/v1/composer/json';
+const COMPOSER_LOCK_ENDPOINT = 'loopress/v1/composer/lock';
+export async function composerRemoteState(wp) {
+    const state = new Map();
+    const { composerJson } = await wp.get(COMPOSER_JSON_ENDPOINT);
+    state.set('composer.json', composerJson);
+    try {
+        const { composerLock } = await wp.get(COMPOSER_LOCK_ENDPOINT);
+        state.set('composer.lock', composerLock);
+    }
+    catch (error) {
+        // A site that never pushed Composer dependencies has no lock yet, the same tolerated 404
+        // as `composer pull`.
+        if (!isApplicative404(error, 'composer.lock not found'))
+            throw error;
+    }
+    return state;
+}
+export async function composerLocalState(rootDir) {
+    const state = new Map();
+    for (const file of ['composer.json', 'composer.lock']) {
+        try {
+            state.set(file, await readFile(join(rootDir, file), 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return state;
+}

package/dist/lib/validate-local.js

@@ -6,12 +6,12 @@ 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', 'pageDir', 'seoDir'];
+const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'seoDir'];
 const DEFAULT_DIR = {
     acfDir: 'acf',
     apiDir: 'api',
     formDir: 'forms',
-    pageDir: 'pages',
+    hooksDir: 'hooks',
     seoDir: 'seo',
     snippetsDir: 'snippets',
 };
@@ -35,20 +35,28 @@ export async function validateLocal(cwd) {
         checked += await checkJsonDir(resolve(key), problems);
     }
     checked += await checkSnippets(resolve('snippetsDir'), problems);
-    checked += await checkApiDir(resolve('apiDir'), problems);
+    checked += await checkPhpDir(resolve('apiDir'), problems, 'API route file is empty');
+    checked += await checkPhpDir(resolve('hooksDir'), problems, 'Hook file is empty');
     return { checked, problems, valid: problems.length === 0 };
 }
-async function checkApiDir(dir, problems) {
-    const entries = await readdirTolerant(dir, { withFileTypes: true });
+// Recursive: both api/ and hooks/ files can live in a nested path-segment directory
+// (invoice-pdf/[order_id].php, content/filters.php), a non-recursive scan would silently
+// never check those.
+async function checkPhpDir(dir, problems, emptyMessage) {
+    const entries = await readdirTolerant(dir, { recursive: true, withFileTypes: true });
     let checked = 0;
     for (const entry of entries) {
         if (!entry.isFile() || !entry.name.endsWith('.php'))
             continue;
         checked += 1;
-        const filePath = join(dir, entry.name);
+        // parentPath is the entry's actual containing directory, which only equals `dir` itself
+        // for a top-level file: recursive readdir() nests entry.name to the basename alone, so
+        // join(dir, entry.name) would silently point at the wrong (top-level) path for anything
+        // one level deep or more.
+        const filePath = join(entry.parentPath, entry.name);
         const content = await readFile(filePath, 'utf8');
         if (content.trim() === '')
-            problems.push({ file: filePath, message: 'API route file is empty' });
+            problems.push({ file: filePath, message: emptyMessage });
     }
     return checked;
 }

package/dist/lib/wp-client.d.ts

@@ -9,6 +9,9 @@ export declare class WpClient {
     constructor(siteUrl: string, token: string);
     delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
+    getAll<T>(path: string, options?: RequestOptions & {
+        perPage?: number;
+    }): Promise<T[]>;
     post<T = unknown>(path: string, json?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
     put<T = unknown>(path: string, json?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
     private request;
@@ -17,6 +20,8 @@ type RequestOptions = {
     timeoutMs?: number;
 };
 export declare function isNotFoundError(error: unknown): boolean;
+export declare function isApplicative404(error: unknown, marker: string): boolean;
 export declare function isTimeoutError(error: unknown): boolean;
+export declare function isInvalidPageNumber(error: unknown): boolean;
 export declare function formatWpError(error: unknown, url: string, timeoutMs?: number): string;
 export {};

package/dist/lib/wp-client.js

@@ -22,6 +22,32 @@ export class WpClient {
     async get(path, options) {
         return this.request('get', path, undefined, options);
     }
+    // Fetches every page of a paginated WP REST collection by walking `?page=N`, stopping on the
+    // first short page or on WordPress core's 400 "rest_post_invalid_page_number" past the last
+    // one. `path` may already carry query params. Use for `wp/v2/*` list endpoints, which cap at
+    // 100 items per request.
+    async getAll(path, options) {
+        const perPage = options?.perPage ?? 100;
+        const separator = path.includes('?') ? '&' : '?';
+        const all = [];
+        for (let page = 1;; page += 1) {
+            let batch;
+            try {
+                batch = await this.get(`${path}${separator}per_page=${perPage}&page=${page}`, options);
+            }
+            catch (error) {
+                if (isInvalidPageNumber(error))
+                    break;
+                throw error;
+            }
+            if (!Array.isArray(batch) || batch.length === 0)
+                break;
+            all.push(...batch);
+            if (batch.length < perPage)
+                break;
+        }
+        return all;
+    }
     async post(path, json, options) {
         return this.request('post', path, json, options);
     }
@@ -43,10 +69,40 @@ export function isNotFoundError(error) {
     const cause = error?.cause;
     return cause?.response?.statusCode === 404;
 }
+// A 404 a Loopress controller raises on purpose, identified by its JSON body's `error` field
+// (e.g. `{"error": "composer.lock not found"}` from ComposerController). Narrower than
+// isNotFoundError: a bare 404 also covers the route being absent because the plugin isn't
+// installed or predates the feature, which callers must still surface normally.
+export function isApplicative404(error, marker) {
+    if (!isNotFoundError(error))
+        return false;
+    const body = error.cause?.response?.body;
+    if (!body)
+        return false;
+    try {
+        return JSON.parse(body).error === marker;
+    }
+    catch {
+        return false;
+    }
+}
 export function isTimeoutError(error) {
     const cause = error?.cause;
     return cause?.name === 'TimeoutError';
 }
+// WordPress core answers 400 with this `code` when `?page=N` is past the last page of a
+// collection, which is how `WpClient.getAll` knows it has walked them all.
+export function isInvalidPageNumber(error) {
+    const body = error.cause?.response?.body;
+    if (!body)
+        return false;
+    try {
+        return JSON.parse(body).code === 'rest_post_invalid_page_number';
+    }
+    catch {
+        return false;
+    }
+}
 export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     const err = error;
     const status = err.response?.statusCode;

package/dist/types/plugin.d.ts

@@ -8,6 +8,7 @@ export type InstalledPlugin = {
 export type WpNativePlugin = {
     name: string;
     plugin: string;
+    plugin_uri: string;
     status: 'active' | 'inactive' | 'network-active';
     version: string;
 };

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

@@ -23,22 +23,36 @@ export interface LoopressProjectConfiguration {
      * Directory where forms (WPForms today) are read from and written to, relative to rootDir.
      */
     formDir?: string;
-    /**
-     * Directory where WordPress pages are read from and written to, relative to rootDir.
-     */
-    pageDir?: string;
     /**
      * Directory where custom API route files are read from and written to, relative to rootDir.
      */
     apiDir?: string;
+    /**
+     * Directory where hook files (WordPress actions, filters, and scheduled tasks) are read from and written to, relative to rootDir.
+     */
+    hooksDir?: string;
+    /**
+     * Directory where single-page app bundles are read from and written to, relative to rootDir. Each subdirectory is one app: a loopress.app.json plus a built dist/ folder.
+     */
+    appsDir?: string;
+    /**
+     * 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;
     /**
      * Project identifier from the global Loopress config. When set, takes precedence over the currently active project in the global config.
      */
     projectId?: string;
     /**
-     * WordPress.org plugins managed by Loopress. Keys are plugin slugs; values are written as "latest" since installs go through WordPress's native plugin API, which only installs the current version. Older files may still have a pinned version string here from before this was the case; it is read but no longer acted on.
+     * WordPress.org plugins managed by Loopress, installed via Composer + WPackagist on the site. Keys are plugin slugs. A value is either an exact version to pin (e.g. "9.4.2") or "latest" to track the newest release on every push. Removing an entry uninstalls the plugin on the next push. Ignored when a composer.json exists in rootDir (that file becomes authoritative).
      */
     plugins?: {
         [k: string]: string;
     };
+    /**
+     * WordPress.org themes managed by Loopress, installed via Composer + WPackagist on the site. Keys are theme slugs; values are an exact version or "latest". Loopress manages installed theme versions only, it never switches the active theme. Ignored when a composer.json exists in rootDir.
+     */
+    themes?: {
+        [k: string]: string;
+    };
 }

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

@@ -0,0 +1,31 @@
+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 type LocalOption = {
+    autoload: string;
+    name: string;
+    readonly?: boolean;
+    value: unknown;
+};
+export type RemoteOption = {
+    autoload: string;
+    name: string;
+    value: unknown;
+};
+export type ListedOption = {
+    autoload: string;
+    confirmed: boolean;
+    core: boolean;
+    guess: null | string;
+    name: string;
+    pluginName: null | string;
+};
+export declare function isReservedOptionName(name: string): boolean;
+export declare function defaultReadonlyFor(name: string): boolean;
+export declare function optionFileName(name: string): string;
+export declare function partitionByReadonly(tracked: LocalOption[]): {
+    skipped: LocalOption[];
+    writable: LocalOption[];
+};
+export declare function parseLocalOption(raw: string): LocalOption;

package/dist/utils/option-format.js

@@ -0,0 +1,51 @@
+export const OPTIONS_ENDPOINT = 'loopress/v1/options';
+export function optionEndpoint(name) {
+    return `${OPTIONS_ENDPOINT}/${encodeURIComponent(name)}`;
+}
+// Mirrors OptionsService::RESERVED_NAMES on the WordPress side (the actual, unbypassable
+// 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
+// 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'];
+export function isReservedOptionName(name) {
+    return RESERVED_OPTION_NAMES.includes(name);
+}
+export function defaultReadonlyFor(name) {
+    return READONLY_BY_DEFAULT_OPTION_NAMES.includes(name);
+}
+export function optionFileName(name) {
+    return `${name}.json`;
+}
+// Splits tracked options into what `push` may write and what it must skip: readonly is a local
+// policy flag (see READONLY_BY_DEFAULT_OPTION_NAMES), never something WordPress itself enforces.
+export function partitionByReadonly(tracked) {
+    const writable = [];
+    const skipped = [];
+    for (const option of tracked)
+        (option.readonly ? skipped : writable).push(option);
+    return { skipped, writable };
+}
+export function parseLocalOption(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('not a JSON object');
+    }
+    const { autoload, name, value } = parsed;
+    if (typeof name !== 'string' || name === '') {
+        throw new Error('missing a "name" string');
+    }
+    if (typeof autoload !== 'string') {
+        throw new TypeError('missing an "autoload" string');
+    }
+    // `value` itself is deliberately untyped (a WP option can hold any JSON-safe value, including
+    // null); only the key's presence is checked, so a hand-edited file that dropped it entirely is
+    // rejected here rather than silently pushing an `undefined` value to WordPress.
+    if (value === undefined) {
+        throw new Error('missing a "value" field');
+    }
+    return parsed;
+}

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

@@ -0,0 +1,26 @@
+export declare const SYNC_TIMEOUT_MS = 600000;
+export type SyncIntent = {
+    libraries?: Record<string, string>;
+    plugins?: Record<string, string>;
+    themes?: Record<string, string>;
+};
+export type SyncPayload = {
+    force: boolean;
+    intent: SyncIntent;
+    lock: null | string;
+};
+export type SyncResponse = {
+    composerJson: string;
+    composerLock: string;
+    message: string;
+    output: string;
+    removed: string[];
+};
+export type Collision = {
+    installedVersion: string;
+    path: string;
+    slug: string;
+    type: 'plugin' | 'theme';
+};
+export declare function parseCollisions(error: unknown): Collision[] | null;
+export declare function isDowngrade(from: string, to: string): boolean;