@loopress/cli 0.34.0 → 0.35.0

package/dist/commands/snippet/push.js

@@ -1,5 +1,5 @@
 import { Args } from '@oclif/core';
-import { readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { readFile, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { loadSnippets as loadSnippetsFromDisk } from '../../lib/load-snippets.js';
 import { errorCode, errorMessage, isRecord } from '../../lib/narrow.js';
@@ -10,6 +10,7 @@ import { isNotFoundError } from '../../lib/wp-client.js';
 import {} from '../../types/snippet.generated.js';
 import {} from '../../types/snippet.js';
 import { pluralize } from '../../utils/pluralize.js';
+import { renameWithRetry } from '../../utils/rename-retry.js';
 import { normalizeSnippet, SNIPPETS_ENDPOINT, stripPhpOpeningTag } from '../../utils/snippet-format.js';
 import { toSlug } from '../../utils/to-slug.js';
 export default class Push extends PushCommand {
@@ -89,7 +90,7 @@ export default class Push extends PushCommand {
             return;
         const newPath = join(dir, `${canonicalBase}${ext}`);
         const newMetaPath = join(dir, `${canonicalBase}.json`);
-        await rename(snippet.path, newPath);
+        await renameWithRetry(snippet.path, newPath);
         await writeFile(newMetaPath, JSON.stringify(meta, null, 2) + '\n');
         await rm(oldMetaPath, { force: true });
     }

package/dist/lib/base.d.ts

@@ -50,6 +50,7 @@ export declare abstract class LoopressCommand extends Command {
     protected resolveOptionsPath(override?: string): string;
     protected resolveSnippetsPath(override?: string): string;
     protected resolveThemeStylesPath(override?: string): string;
+    private assertSiteSupportsResource;
     private pickEnvironment;
     private resolveEnvironment;
 }

package/dist/lib/base.js

@@ -8,7 +8,8 @@ import {} from '../types/config.js';
 import { readLocalConfig } from '../utils/loopress-config.js';
 import { pluralize } from '../utils/pluralize.js';
 import { resolveResourceDir } from '../utils/resource-dirs.js';
-import { getCapabilities } from './capabilities.js';
+import { commandResourceKind, getCapabilities, missingIntegration, unsupportedMessage } from './capabilities.js';
+import { declaredPlugins } from './declared-plugins.js';
 import { activateExclusions } from './exclude.js';
 import { isInteractive } from './interactive.js';
 import { isAppPasswordStale, rotateAppPassword } from './rotate-app-password.js';
@@ -104,6 +105,7 @@ export class LoopressCommand extends Command {
             honors: this.ctor.honorsExclude,
         });
         await this.maybeAutoRotate();
+        await this.assertSiteSupportsResource();
     }
     // Silent, best-effort: a stale app password still works, so a failed rotation attempt
     // (offline, site down) just tries again on the next command instead of blocking this one.
@@ -218,6 +220,25 @@ export class LoopressCommand extends Command {
     resolveThemeStylesPath(override) {
         return resolveResourceDir('themeStyles', this.localConfig, override);
     }
+    // A command on a single kind of resource (`lps hook push`) says what `lps push` says when the
+    // site can't hold it, instead of failing on the 404. A site whose capabilities can't be read
+    // (too old a plugin, unreachable) lets the command run and report its own error.
+    async assertSiteSupportsResource() {
+        const kind = commandResourceKind(this.id);
+        if (!kind)
+            return;
+        let missing;
+        try {
+            missing = missingIntegration(kind, await this.capabilities());
+        }
+        catch {
+            return;
+        }
+        if (!missing)
+            return;
+        const declared = await declaredPlugins({ localConfig: this.localConfig, rootDir: this.rootDir, siteName: this.siteConfig.name });
+        this.error(unsupportedMessage(missing, this.siteConfig.name, declared));
+    }
     pickEnvironment(project, envName) {
         const env = project.environments[envName];
         if (!env) {

package/dist/lib/capabilities.d.ts

@@ -36,6 +36,11 @@ export declare function integrationFix(missing: MissingIntegration, declared: {
     fromComposer: boolean;
     plugins: string[];
 }): string | undefined;
+export declare function commandResourceKind(commandId: string | undefined): ResourceDirKind | undefined;
+export declare function unsupportedMessage(missing: MissingIntegration, site: string, declared: {
+    fromComposer: boolean;
+    plugins: string[];
+}): string;
 export type ThemeActivation = {
     active: string;
     changed: boolean;

package/dist/lib/capabilities.js

@@ -78,6 +78,22 @@ export function integrationFix(missing, declared) {
     const where = declared.fromComposer ? `wpackagist-plugin/${first} in composer.json` : `"${first}" in loopress.json plugins`;
     return `Declare ${first}${or} (${where}), then activate it: ${activate(first)}`;
 }
+// The command topics that act on one kind of resource the site may be unable to hold
+// (`lps hook push`, `lps acf list`...), so they can say so instead of surfacing the 404. `publish`
+// goes through the console, not the site. `scf` is the alias of `acf`.
+const TOPIC_KINDS = { acf: 'acf', api: 'api', block: 'block', form: 'form', hook: 'hooks', page: 'page', pattern: 'pattern', scf: 'acf', snippet: 'snippets' };
+export function commandResourceKind(commandId) {
+    const [topic, action] = (commandId ?? '').split(':', 2);
+    if (!topic || !action || action === 'publish')
+        return undefined;
+    return TOPIC_KINDS[topic];
+}
+// "Not supported by <site>: <reason>. <fix>.", for the single-resource commands.
+export function unsupportedMessage(missing, site, declared) {
+    const fix = integrationFix(missing, declared);
+    const fixSentence = fix ? ` ${fix}.` : '';
+    return `Not supported by ${site}: ${missing.reason}.${fixSentence}`;
+}
 export async function activateTheme(wp, stylesheet) {
     const activation = await wp.post(THEME_ACTIVATE_ENDPOINT, { stylesheet });
     cache.delete(wp);

package/dist/lib/load-snippets.js

@@ -69,10 +69,7 @@ async function readSidecar(metaPath) {
         throw new Error('not a JSON object');
     return meta;
 }
-// Shared by `snippet push` (pushes to the project's own WordPress site) and `snippet publish`
-// (publishes to the Loopress api as a shared source): both read the same local `snippets/`
-// directory the same way. `onSkip` is optional so callers that don't care about per-file
-// warnings (e.g. `snippet publish`) can ignore them; skipped files are simply left out either way.
+// Reads the local `snippets/` directory. `onSkip` is optional: skipped files are simply left out either way.
 export async function loadSnippets(path, onSkip) {
     let files;
     try {

package/dist/lib/push-command.d.ts

@@ -2,6 +2,26 @@ import { LoopressCommand } from './base.js';
 import { type ResourceState } from './diff-state.js';
 import { type ScannedItem } from './environment-urls.js';
 import { type ResourceStateProvider } from './resource-state.js';
+export type DeploymentStep = {
+    command: string;
+    status: 'failed' | 'pushed' | 'skipped';
+};
+type DeploymentPlugins = Array<{
+    active: boolean;
+    slug: string;
+    version: string;
+}>;
+export declare function startDeploymentCollector(): {
+    plugins?: DeploymentPlugins;
+};
+export declare function stopDeploymentCollector(): void;
+export declare function postDeployment(body: {
+    command: string | undefined;
+    plugins?: DeploymentPlugins;
+    status: 'failure' | 'success';
+    steps?: DeploymentStep[];
+    url: string;
+}): Promise<void>;
 export type PushChange = {
     id: string;
     status: 'changed' | 'created' | 'removed' | 'unchanged';
@@ -46,4 +66,6 @@ export declare abstract class PushCommand extends LoopressCommand {
     protected warnEnvironmentUrls(items: ScannedItem[]): void;
     protected writeAfterPushSnapshot(provider: ResourceStateProvider, dir: string, beforeState: ResourceState | undefined): Promise<void>;
     private guardOutsideEdits;
+    private pushedPlugins;
 }
+export {};

package/dist/lib/push-command.js

@@ -7,6 +7,7 @@ import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { authManager } from '../config/auth.manager.js';
 import {} from '../types/config.js';
+import { pinActive, pinVersion } from '../types/plugin.js';
 import { API_URL } from './api-client.js';
 import { LoopressCommand } from './base.js';
 import {} from './diff-state.js';
@@ -33,6 +34,32 @@ function gitState() {
         return {};
     }
 }
+// Set while `lps push` runs its steps in process: they hand over what they would have posted
+// instead of posting, so the run sends one record (and waits at most one timeout).
+let deploymentCollector;
+export function startDeploymentCollector() {
+    deploymentCollector = {};
+    return deploymentCollector;
+}
+export function stopDeploymentCollector() {
+    deploymentCollector = undefined;
+}
+// Best-effort: recording must never interrupt the push flow.
+export async function postDeployment(body) {
+    const token = process.env.LOOPRESS_TOKEN ?? authManager.getAuth()?.token ?? null;
+    if (!token)
+        return;
+    try {
+        await withSpinner('Recording the deployment', async () => got.post(`${API_URL}/deployments`, {
+            headers: { Authorization: `Bearer ${token}` },
+            json: { ...body, ...gitState() },
+            timeout: { request: 3000 },
+        }));
+    }
+    catch {
+        // non-blocking
+    }
+}
 export function pushChanges(local, remote, options = {}) {
     const changes = [...local.keys()]
         .filter((id) => options.writes?.(id) ?? true)
@@ -158,19 +185,14 @@ export class PushCommand extends LoopressCommand {
         }
     }
     async recordDeployment(status) {
-        const token = process.env.LOOPRESS_TOKEN ?? authManager.getAuth()?.token ?? null;
-        if (!token)
+        // Inside `lps push`, the steps only report the plugin inventory: the run posts one record.
+        if (deploymentCollector) {
+            const { plugins } = this.pushedPlugins(status);
+            if (plugins)
+                deploymentCollector.plugins = plugins;
             return;
-        try {
-            await withSpinner('Recording the deployment', async () => got.post(`${API_URL}/deployments`, {
-                headers: { Authorization: `Bearer ${token}` },
-                json: { status, url: this.siteConfig.url, command: this.id, ...gitState() },
-                timeout: { request: 3000 },
-            }));
-        }
-        catch {
-            // non-blocking: recording must never interrupt the push flow
         }
+        await postDeployment({ command: this.id, status, url: this.siteConfig.url, ...this.pushedPlugins(status) });
     }
     async recordSuccess() {
         if (this.dryRun)
@@ -309,6 +331,14 @@ export class PushCommand extends LoopressCommand {
         if (!(await confirm({ default: false, message: 'Overwrite those changes?' })))
             this.error('Aborted.');
     }
+    // The plugin inventory of a landed `plugin:push` (a full `lps push` runs it as a step), read from
+    // loopress.json: slug, pinned version and whether it must be active. Other commands send none.
+    pushedPlugins(status) {
+        if (status !== 'success' || this.id !== 'plugin:push')
+            return {};
+        const plugins = Object.entries(this.localConfig.plugins ?? {}).map(([slug, pin]) => ({ active: pinActive(pin), slug, version: pinVersion(pin) }));
+        return { plugins };
+    }
 }
 function sameEntry(left, right, id) {
     return left.has(id) === right.has(id) && isDeepStrictEqual(left.get(id), right.get(id));

package/dist/lib/validate-local.js

@@ -2,7 +2,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { z } from 'zod';
 import { configManager } from '../config/project-config.manager.js';
-import { PLUGIN_PIN } from '../types/plugin.js';
+import { pinProblem } from '../types/plugin.js';
 import { readLocalBlocks } from '../utils/block-format.js';
 import { COMPOSER_JSON } from '../utils/composer.js';
 import { CPT_SPEC, declaredFileChecker, META_SPEC, PATTERN_SPEC, ROLE_SPEC, TAXONOMY_SPEC } from '../utils/declared-type-format.js';
@@ -259,9 +259,9 @@ function checkLoopressJson(localConfig, problems) {
     }
     for (const [slug, version] of Object.entries(manifest.data)) {
         // The object form is what `plugin pull` writes for a plugin installed but inactive (see PluginPin).
-        if (!PLUGIN_PIN.safeParse(version).success) {
-            problems.push({ file: 'loopress.json', message: `plugin "${slug}" must map to a version string or {version, active}` });
-        }
+        const message = pinProblem(slug, version);
+        if (message)
+            problems.push({ file: 'loopress.json', message });
     }
 }
 async function checkSnippets(dir, problems) {

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

@@ -24,6 +24,7 @@ type RequestOptions = {
 };
 export declare function isNotFoundError(error: unknown): boolean;
 export declare function isForbiddenError(error: unknown): boolean;
+export declare function isFirewallBlock(error: unknown): boolean;
 export declare function isApplicationPasswordsDisabled(error: unknown): boolean;
 export declare function isApplicative404(error: unknown, marker: string): boolean;
 export declare function isConflictCode(error: unknown, code: string): boolean;

package/dist/lib/wp-client.js

@@ -100,6 +100,17 @@ export function isNotFoundError(error) {
 export function isForbiddenError(error) {
     return responseOf(causeOf(error)).statusCode === 403;
 }
+// A 403 whose body is not a WordPress JSON error (`code`/`message`) nor a Loopress `error`
+// refusal: the answer of a firewall (ModSecurity, Imunify360, Wordfence...) in front of PHP.
+export function isFirewallBlock(error) {
+    return isFirewallResponse(responseOf(causeOf(error)));
+}
+function isFirewallResponse({ body, statusCode }) {
+    if (statusCode !== 403)
+        return false;
+    const parsed = parseBody(body);
+    return typeof parsed.code !== 'string' && typeof parsed.message !== 'string' && typeof parsed.error !== 'string';
+}
 // WordPress core answers the authenticated request with this `code` when Application
 // Passwords are turned off for the user (a security plugin, `wp_is_application_passwords_available`
 // filter or the user's role), as opposed to `incorrect_password`/`invalid_username` for bad credentials.
@@ -152,16 +163,8 @@ export function parseBody(body) {
 }
 export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     const { body, statusCode: status } = responseOf(error);
-    if (status === 401 || status === 403) {
-        // A Loopress controller's own `{"error": ...}` on a 403 is a deliberate refusal of this one
-        // request (e.g. OptionsController protecting a secret-looking option), not bad credentials:
-        // pointing at `lps project config` there sends the user the wrong way. WordPress core's own
-        // auth failures use `{code, message}` instead and keep the credentials hint.
-        const refusal = extractLoopressError(body);
-        if (refusal)
-            return `Request refused (${status}) on ${url}: ${refusal}`;
-        return `Authentication failed (${status}) on ${url}. Check your credentials with \`lps project config\`.`;
-    }
+    if (status === 401 || status === 403)
+        return formatAuthError(status, body, url);
     if (status === 404) {
         const reason = extractServerErrorMessage(body);
         return reason
@@ -186,6 +189,23 @@ export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     const message = isRecord(error) && typeof error.message === 'string' ? error.message : '';
     return `Request to ${url} failed: ${message || (code ?? String(error))}`;
 }
+function formatAuthError(status, body, url) {
+    if (isFirewallResponse({ body, statusCode: status }))
+        return firewallMessage(url);
+    // A Loopress controller's own `{"error": ...}` on a 403 is a deliberate refusal of this one
+    // request (e.g. OptionsController protecting a secret-looking option), not bad credentials:
+    // pointing at `lps project config` there sends the user the wrong way. WordPress core's own
+    // auth failures use `{code, message}` instead and keep the credentials hint.
+    const refusal = extractLoopressError(body);
+    if (refusal)
+        return `Request refused (${status}) on ${url}: ${refusal}`;
+    return `Authentication failed (${status}) on ${url}. Check your credentials with \`lps project config\`.`;
+}
+// A 403 that is not a WordPress JSON error never came from WordPress: a web application
+// firewall answered before PHP ran, and no credential change will fix it.
+function firewallMessage(url) {
+    return `Request blocked (403) on ${url}: the response is not a WordPress error, so a firewall or security plugin (ModSecurity, Imunify360, Wordfence) probably blocked the request. Allow-list the request or your IP in the firewall, then retry.`;
+}
 const NETWORK_ERROR_HINTS = {
     ECONNREFUSED: 'connection refused, the site may be down',
     ECONNRESET: 'connection reset by the server',

package/dist/types/plugin.d.ts

@@ -16,7 +16,8 @@ export type WpNativePlugin = {
 export declare const PLUGIN_PIN: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     active: z.ZodExactOptional<z.ZodBoolean>;
     version: z.ZodString;
-}, z.core.$strip>]>;
+}, z.core.$strict>]>;
+export declare function pinProblem(slug: string, pin: unknown): string | undefined;
 export type PluginPin = z.infer<typeof PLUGIN_PIN>;
 export type PluginManifest = Record<string, PluginPin>;
 export declare const pinVersion: (pin: PluginPin) => string;

package/dist/types/plugin.js

@@ -1,7 +1,38 @@
 import { z } from 'zod';
 // A bare version string means "installed and active"; the object form records a plugin that
 // must stay installed but inactive.
-export const PLUGIN_PIN = z.union([z.string(), z.object({ active: z.boolean().exactOptional(), version: z.string() })]);
+// Strict: an unknown key is a typo (`activate` for `active`) that would otherwise be dropped.
+export const PLUGIN_PIN = z.union([z.string(), z.strictObject({ active: z.boolean().exactOptional(), version: z.string() })]);
+const PIN_KEYS = ['active', 'version'];
+// Levenshtein distance, enough to tell a typo of a pin key ("activate", "verison") from another key.
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const substitution = (previous[j - 1] ?? 0) + (a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1);
+            current.push(Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution));
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+// Why a loopress.json plugin pin is invalid, or undefined when it is fine.
+export function pinProblem(slug, pin) {
+    if (PLUGIN_PIN.safeParse(pin).success)
+        return undefined;
+    if (pin !== null && typeof pin === 'object' && !Array.isArray(pin)) {
+        const unknown = Object.keys(pin).filter((key) => !PIN_KEYS.includes(key));
+        if (unknown.length > 0) {
+            const hints = unknown.map((key) => {
+                const near = PIN_KEYS.find((known) => editDistance(key.toLowerCase(), known) <= 2);
+                return near ? `"${key}" (did you mean "${near}"?)` : `"${key}"`;
+            });
+            return `plugin "${slug}" has unknown key(s) ${hints.join(', ')}: a pin is a version string or {version, active}`;
+        }
+    }
+    return `plugin "${slug}" must map to a version string or {version, active}`;
+}
 export const pinVersion = (pin) => (typeof pin === 'string' ? pin : pin.version);
 // No pin at all (a slug loopress.json doesn't list) keeps the default: active.
 export const pinActive = (pin) => typeof pin === 'string' || pin?.active !== false;

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

@@ -26,6 +26,7 @@ export type ListedOption = {
 };
 export declare function isReservedOptionName(name: string): boolean;
 export declare function defaultReadonlyFor(name: string): boolean;
+export declare function isWindowsReservedName(name: string): boolean;
 export declare function optionFileName(name: string): string;
 export declare function partitionByReadonly(tracked: LocalOption[]): {
     skipped: LocalOption[];

package/dist/utils/option-format.js

@@ -38,7 +38,17 @@ export function isReservedOptionName(name) {
 export function defaultReadonlyFor(name) {
     return READONLY_BY_DEFAULT_OPTION_NAMES.includes(name);
 }
+// Windows refuses these device names as a file name, with or without an extension (`NUL.json`).
+const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])$/i;
+export function isWindowsReservedName(name) {
+    return WINDOWS_RESERVED_NAME.test(name.split('.', 1)[0]?.trimEnd() ?? '');
+}
+function reservedNameMessage(name) {
+    return `Option name "${name}" is a reserved Windows file name (CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9) and cannot be tracked as ${name}.json`;
+}
 export function optionFileName(name) {
+    if (isWindowsReservedName(name))
+        throw new Error(reservedNameMessage(name));
     return `${name}.json`;
 }
 // Splits tracked options into what `push` may write and what it must skip: readonly is a local
@@ -54,7 +64,10 @@ const REFS_ERROR = '"refs" must map a value path to a post type, e.g. {"purchase
 // Each check's message is the error thrown for it, the first failing one wins. Loose: unknown
 // keys (`readonly`, future ones) pass through untouched.
 const LOCAL_OPTION = z.looseObject({
-    name: z.string('missing a "name" string').min(1, 'missing a "name" string'),
+    name: z
+        .string('missing a "name" string')
+        .min(1, 'missing a "name" string')
+        .refine((name) => !isWindowsReservedName(name), { error: (issue) => reservedNameMessage(String(issue.input)) }),
     autoload: z.string('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

package/dist/utils/plugins.d.ts

@@ -37,5 +37,8 @@ export type MergeResult<P extends PluginPin = PluginPin> = {
 export declare function describePin(pin: PluginPin): string;
 export declare function mergePluginManifest<P extends PluginPin>(existing: Record<string, P>, incoming: Record<string, P>): MergeResult<P>;
 export declare function parseInstalledPlugins(raw: WpNativePlugin[]): InstalledPlugin[];
+export declare function preferredCopy<P extends {
+    file: string;
+}>(copies: P[], slug: string): P | undefined;
 export declare function diffPlugins(manifest: PluginManifest, installed: InstalledPlugin[], managedSlugs?: Set<string>): PluginDiff;
 export declare function lockedWpackagistSlugs(composerLock: null | string, kind: 'plugin' | 'theme'): Set<string>;

package/dist/utils/plugins.js

@@ -46,12 +46,17 @@ export function parseInstalledPlugins(raw) {
     }))
         .filter((plugin) => !LOOPRESS_PLUGIN_SLUGS.has(plugin.slug));
 }
+// Composer installs a plugin into `<slug>/`; a site can also hold another copy under the same
+// slug (core's `hello.php` is Hello Dolly). Prefer the one in the slug's folder.
+export function preferredCopy(copies, slug) {
+    return copies.find((p) => p.file.startsWith(`${slug}/`)) ?? copies[0];
+}
 export function diffPlugins(manifest, installed, 
 // Slugs Loopress currently manages, from the local composer.lock's wpackagist-plugin/*
 // entries. Empty for a loopress.json-only project that doesn't keep a lockfile in the repo:
 // `toRemove` then stays empty (removals still happen server-side, they just aren't previewed).
 managedSlugs = new Set()) {
-    const installedMap = new Map(installed.map((p) => [p.slug, p]));
+    const installedMap = new Map(installed.map((p) => [p.slug, preferredCopy(installed.filter((q) => q.slug === p.slug), p.slug) ?? p]));
     const toInstall = [];
     const toPin = [];
     const toActivate = [];

package/dist/utils/rename-retry.d.ts

@@ -0,0 +1 @@
+export declare function renameWithRetry(from: string, to: string, attempts?: number, baseDelayMs?: number): Promise<void>;

package/dist/utils/rename-retry.js

@@ -0,0 +1,20 @@
+import { rename } from 'node:fs/promises';
+import { setTimeout as sleep } from 'node:timers/promises';
+const RETRYABLE_CODES = new Set(['EBUSY', 'EPERM']);
+// On Windows, an editor, an antivirus or the search indexer can briefly hold a file open and make
+// rename() fail with EPERM/EBUSY. Those clear within milliseconds, so retry a few times with a
+// growing delay before giving up. Other errors (ENOENT, EEXIST...) are thrown right away.
+export async function renameWithRetry(from, to, attempts = 5, baseDelayMs = 50) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error instanceof Error && 'code' in error ? String(error.code) : '';
+            if (!RETRYABLE_CODES.has(code) || attempt >= attempts)
+                throw error;
+            await sleep(baseDelayMs * attempt);
+        }
+    }
+}

package/dist/utils/version.d.ts

@@ -1,2 +1,4 @@
 export declare function isExactVersion(value: string): boolean;
 export declare function compareVersions(a: string, b: string): null | number;
+export type VersionJump = 'major' | 'minor' | 'patch';
+export declare function versionJump(from: string, to: string): null | VersionJump;

package/dist/utils/version.js

@@ -19,3 +19,24 @@ export function isExactVersion(value) {
 export function compareVersions(a, b) {
     return validate(a) && validate(b) ? cmp(a, b) : null;
 }
+// How far `from` is behind `to`: the first numeric segment that differs, major, minor, then
+// anything finer is a patch. Null when `from` is not behind `to` or either isn't comparable.
+export function versionJump(from, to) {
+    const order = compareVersions(from, to);
+    if (order === null || order >= 0)
+        return null;
+    const a = numericSegments(from);
+    const b = numericSegments(to);
+    if (a[0] !== b[0])
+        return 'major';
+    if ((a[1] ?? 0) !== (b[1] ?? 0))
+        return 'minor';
+    return 'patch';
+}
+function numericSegments(version) {
+    const core = (version.split('-', 1)[0] ?? version).replace(/^v/i, '');
+    return core.split('.').map((part) => {
+        const n = Number(part);
+        return Number.isNaN(n) ? 0 : Math.trunc(n);
+    });
+}

package/dist/utils/wporg.d.ts

@@ -0,0 +1,5 @@
+export declare const WPORG_INFO = "https://api.wordpress.org/plugins/info/1.2/";
+export declare function requestPluginInfo(slug: string, { versions }?: {
+    versions?: boolean;
+}): Promise<null | Record<string, unknown>>;
+export declare function fetchPluginInfo(slug: string): Promise<null | Record<string, unknown>>;

package/dist/utils/wporg.js

@@ -0,0 +1,41 @@
+import got from 'got';
+export const WPORG_INFO = 'https://api.wordpress.org/plugins/info/1.2/';
+// The WordPress.org plugin_information answer for one slug, or null when the plugin isn't
+// listed there (zip, premium), or {error: 'closed'} for a closed one. Throws when the API can't be reached or answers with an error.
+// `versions` adds every released version (`versions`: version -> download URL) to the answer.
+export async function requestPluginInfo(slug, { versions = false } = {}) {
+    try {
+        const body = await got(WPORG_INFO, {
+            searchParams: {
+                action: 'plugin_information',
+                'request[slug]': slug,
+                ...(versions && { 'request[fields][versions]': '1' }),
+            },
+            timeout: { request: 10_000 },
+        }).json();
+        // A removed plugin answers {error: 'closed'}: kept so callers can tell it from an unlisted one.
+        if (typeof body === 'object' && 'error' in body && body.error === 'closed')
+            return body;
+        return typeof body === 'object' && !('error' in body) ? body : null;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+}
+// Same lookup, but an unreachable API is reported as null too.
+export async function fetchPluginInfo(slug) {
+    try {
+        return await requestPluginInfo(slug);
+    }
+    catch {
+        return null;
+    }
+}
+function isNotFound(error) {
+    if (typeof error !== 'object' || error === null || !('response' in error))
+        return false;
+    const { response } = error;
+    return typeof response === 'object' && response !== null && 'statusCode' in response && response.statusCode === 404;
+}