@loopress/cli 0.21.0 → 0.23.0

package/dist/lib/load-snippets.js

@@ -8,12 +8,72 @@ const TYPE_BY_EXTENSION = {
     '.php': 'php',
     '.txt': 'text',
 };
+// One snippet's files are read in isolation: a corrupted or hand-broken sidecar (bad JSON,
+// unreadable file, ...) must only skip that snippet, not abort loading every other one.
+async function loadSnippet(path, file, onSkip) {
+    const ext = extname(file);
+    if (!Object.hasOwn(TYPE_BY_EXTENSION, ext))
+        return undefined;
+    const filePath = join(path, file);
+    const metaPath = join(path, `${basename(file, ext)}.json`);
+    let content;
+    try {
+        content = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        onSkip?.(`Skipping "${filePath}": ${error.message}`);
+        return undefined;
+    }
+    let id;
+    let name;
+    let type;
+    let isActive = false;
+    let tags = [];
+    let location = null;
+    let insertMethod = null;
+    let priority = 10;
+    let shortcodeAttributes = [];
+    try {
+        const metaContent = await readFile(metaPath, 'utf8');
+        const meta = JSON.parse(metaContent);
+        id = meta.id;
+        // `||`, not `??`: an empty-string name in the sidecar JSON counts as absent too.
+        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+        name = meta.name || undefined;
+        type = parseType(meta.type) ?? undefined;
+        isActive = Boolean(meta.active);
+        tags = Array.isArray(meta.tags) ? meta.tags.map(String) : [];
+        location = parseLocation(meta.location);
+        insertMethod = parseInsertMethod(meta.insertMethod);
+        priority = meta.priority ?? 10;
+        shortcodeAttributes = Array.isArray(meta.shortcodeAttributes) ? meta.shortcodeAttributes.map(String) : [];
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            onSkip?.(`Skipping "${metaPath}": ${error.message}`);
+            return undefined;
+        }
+    }
+    const resolvedType = type ?? (Object.hasOwn(TYPE_BY_EXTENSION, ext) ? TYPE_BY_EXTENSION[ext] : 'php');
+    return {
+        active: isActive,
+        code: content,
+        id,
+        insertMethod: insertMethod ?? 'auto',
+        location: location ?? defaultLocationForType(resolvedType),
+        name: name ?? basename(file, ext),
+        path: filePath,
+        priority,
+        shortcodeAttributes,
+        tags,
+        type: resolvedType,
+    };
+}
 // 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.
 export async function loadSnippets(path, onSkip) {
-    const snippets = [];
     let files;
     try {
         files = await readdir(path);
@@ -21,66 +81,11 @@ export async function loadSnippets(path, onSkip) {
     catch (error) {
         throw new Error(`Error loading snippets: ${error.message}`, { cause: error });
     }
+    const snippets = [];
     for (const file of files) {
-        const ext = extname(file);
-        if (!Object.hasOwn(TYPE_BY_EXTENSION, ext))
-            continue;
-        const filePath = join(path, file);
-        const metaPath = join(path, `${basename(file, ext)}.json`);
-        // One snippet's files are read in isolation: a corrupted or hand-broken sidecar (bad JSON,
-        // unreadable file, ...) must only skip that snippet, not abort loading every other one.
-        let content;
-        try {
-            content = await readFile(filePath, 'utf8');
-        }
-        catch (error) {
-            onSkip?.(`Skipping "${filePath}": ${error.message}`);
-            continue;
-        }
-        let id;
-        let name;
-        let type;
-        let isActive = false;
-        let tags = [];
-        let location = null;
-        let insertMethod = null;
-        let priority = 10;
-        let shortcodeAttributes = [];
-        try {
-            const metaContent = await readFile(metaPath, 'utf8');
-            const meta = JSON.parse(metaContent);
-            id = meta.id;
-            // `||`, not `??`: an empty-string name in the sidecar JSON counts as absent too.
-            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-            name = meta.name || undefined;
-            type = parseType(meta.type) ?? undefined;
-            isActive = Boolean(meta.active);
-            tags = Array.isArray(meta.tags) ? meta.tags.map(String) : [];
-            location = parseLocation(meta.location);
-            insertMethod = parseInsertMethod(meta.insertMethod);
-            priority = meta.priority ?? 10;
-            shortcodeAttributes = Array.isArray(meta.shortcodeAttributes) ? meta.shortcodeAttributes.map(String) : [];
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT') {
-                onSkip?.(`Skipping "${metaPath}": ${error.message}`);
-                continue;
-            }
-        }
-        const resolvedType = type ?? (Object.hasOwn(TYPE_BY_EXTENSION, ext) ? TYPE_BY_EXTENSION[ext] : 'php');
-        snippets.push({
-            active: isActive,
-            code: content,
-            id,
-            insertMethod: insertMethod ?? 'auto',
-            location: location ?? defaultLocationForType(resolvedType),
-            name: name ?? basename(file, ext),
-            path: filePath,
-            priority,
-            shortcodeAttributes,
-            tags,
-            type: resolvedType,
-        });
+        const snippet = await loadSnippet(path, file, onSkip);
+        if (snippet)
+            snippets.push(snippet);
     }
     return snippets;
 }

package/dist/lib/local-callback-server.js

@@ -17,20 +17,25 @@ function parseFormData(body) {
 export async function waitForLocalCallback(options) {
     const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
     return new Promise((resolve, reject) => {
-        function finish(res, page, settle) {
+        function finish(res, page) {
             res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
             res.end(page);
             clearTimeout(timer);
             server.close();
-            settle();
         }
         async function handleIncoming(req, res) {
             try {
                 const url = new URL(req.url ?? '/', 'http://localhost');
                 const body = req.method === 'POST' ? parseFormData(await readBody(req)) : {};
                 options.handleRequest(url, {
-                    rejectWithPage(page, error) { finish(res, page, () => { reject(error); }); },
-                    resolveWithPage(page, value) { finish(res, page, () => { resolve(value); }); },
+                    rejectWithPage(page, error) {
+                        finish(res, page);
+                        reject(error);
+                    },
+                    resolveWithPage(page, value) {
+                        finish(res, page);
+                        resolve(value);
+                    },
                     respondBadRequest(message) {
                         res.writeHead(400, { 'Content-Type': 'text/plain' });
                         res.end(message);

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

@@ -10,4 +10,7 @@ export declare abstract class PushCommand extends LoopressCommand {
     protected reportTaskFailure(message: string, error: unknown, task?: {
         output: string;
     }): never;
+    protected runPushTasks<T>(items: T[], label: (item: T) => string, task: (item: T, task?: {
+        output: string;
+    }) => Promise<void>): Promise<void>;
 }

package/dist/lib/push-command.js

@@ -1,9 +1,9 @@
-import { confirm } from '@inquirer/prompts';
 import got from 'got';
+import { Listr } from 'listr2';
 import { authManager } from '../config/auth.manager.js';
 import { API_URL } from './api-client.js';
 import { LoopressCommand } from './base.js';
-import { isInteractive } from './interactive.js';
+import { guardProductionPush } from './guard-production-push.js';
 export class PushCommand extends LoopressCommand {
     failedCount = 0;
     // Refusals of the production guard never reach the site, so they must not pollute the
@@ -15,20 +15,16 @@ export class PushCommand extends LoopressCommand {
         }
         return super.catch(err);
     }
-    // Pushing to an environment named "production" needs explicit intent: a TTY confirmation
-    // (Enter accepts), or --yes in scripts and CI. Dry runs are exempt, they change nothing.
     async guardProductionPush() {
-        if (this.siteConfig.name.toLowerCase() !== 'production' || this.dryRun || this.yes)
-            return;
-        if (!isInteractive()) {
-            this.refusedByGuard = true;
-            this.error('Target environment is "production". Pass --yes to confirm the push in a non-interactive run.');
-        }
-        const isProceed = await confirm({ default: true, message: `Push to production (${this.siteConfig.url})?` });
-        if (!isProceed) {
-            this.refusedByGuard = true;
-            this.error('Aborted.');
-        }
+        await guardProductionPush({
+            dryRun: this.dryRun,
+            error: (message) => this.error(message),
+            onRefuse: () => {
+                this.refusedByGuard = true;
+            },
+            siteConfig: this.siteConfig,
+            yes: this.yes,
+        });
     }
     async init() {
         await super.init();
@@ -66,4 +62,15 @@ export class PushCommand extends LoopressCommand {
         this.failedCount++;
         throw error;
     }
+    // Shared shape of every resource's push list: sequential (`concurrent: false` avoids
+    // clobbering `failedCount` and interleaving WordPress writes), and a failing item never
+    // stops its siblings (`exitOnError: false`) so `failedCount` reflects every failure, not
+    // just the first. `label` feeds the "Push <label>" task title; `task` does the actual work
+    // and reports its own failure through `reportTaskFailure`.
+    async runPushTasks(items, label, task) {
+        await new Listr(items.map((item) => ({
+            task: async (_ctx, taskCtx) => task(item, taskCtx),
+            title: `Push ${label(item)}`,
+        })), { concurrent: false, exitOnError: false, renderer: this.jsonEnabled() ? 'silent' : 'default' }).run();
+    }
 }

package/dist/lib/put-or-create.d.ts

@@ -0,0 +1,13 @@
+import { type WpClient } from './wp-client.js';
+type PutOrCreateOptions = {
+    id: null | number;
+    payload: Record<string, unknown>;
+    postEndpoint: string;
+    postPayload?: Record<string, unknown>;
+    putEndpoint: (id: number) => string;
+};
+export declare function putOrCreate<T>(wp: WpClient, options: PutOrCreateOptions): Promise<{
+    body: T;
+    created: boolean;
+}>;
+export {};

package/dist/lib/put-or-create.js

@@ -0,0 +1,19 @@
+import { isNotFoundError } from './wp-client.js';
+// Update-or-create dance shared by every id-based resource (form, page, seo redirect,
+// snippet, unlike ACF which is key-based and only ever POSTs): PUT to the known id, and only
+// fall back to POST when the site doesn't recognize that id (404), e.g. a fresh install or a
+// database reset.
+export async function putOrCreate(wp, options) {
+    const { id, payload, postEndpoint, postPayload = payload, putEndpoint } = options;
+    if (id !== null) {
+        try {
+            const body = await wp.put(putEndpoint(id), payload);
+            return { body, created: false };
+        }
+        catch (error) {
+            if (!isNotFoundError(error))
+                throw error;
+        }
+    }
+    return { body: await wp.post(postEndpoint, postPayload), created: true };
+}

package/dist/lib/readdir-tolerant.d.ts

@@ -0,0 +1,5 @@
+import { type Dirent } from 'node:fs';
+export declare function readdirTolerant(dir: string): Promise<string[]>;
+export declare function readdirTolerant(dir: string, options: {
+    withFileTypes: true;
+}): Promise<Dirent[]>;

package/dist/lib/readdir-tolerant.js

@@ -0,0 +1,11 @@
+import { readdir } from 'node:fs/promises';
+export async function readdirTolerant(dir, options) {
+    try {
+        return options?.withFileTypes ? await readdir(dir, { withFileTypes: true }) : await readdir(dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}

package/dist/lib/resolve-linked-project.d.ts

@@ -0,0 +1,8 @@
+import { type LoopressLocalConfig } from '../utils/loopress-config.js';
+type LinkedProject = {
+    apiProjectId: string;
+    localConfig: LoopressLocalConfig;
+    token: string;
+};
+export declare function resolveLinkedProject(fail: (message: string) => never): Promise<LinkedProject>;
+export {};

package/dist/lib/resolve-linked-project.js

@@ -0,0 +1,27 @@
+import { authManager } from '../config/auth.manager.js';
+import { configManager } from '../config/project-config.manager.js';
+import { readLocalConfig } from '../utils/loopress-config.js';
+// Shared preamble for `api publish` and `snippet publish`. Both target the Loopress cloud (never
+// a WordPress site), so neither extends `LoopressCommand`/`PushCommand` and neither needs an
+// environment resolved, but both need a logged-in user and a project already linked to the
+// account (`lps project push`). `fail` is the caller's `this.error`, so its messages keep
+// oclif's formatting and exit code; typed `=> never` so callers still narrow after the guards.
+export async function resolveLinkedProject(fail) {
+    const token = process.env.LOOPRESS_TOKEN ?? authManager.getAuth()?.token;
+    if (!token) {
+        fail('Not logged in. Run `lps login` first.');
+    }
+    const localConfig = await readLocalConfig();
+    const projectId = localConfig.projectId ?? configManager.getCurrentProject()?.id;
+    if (!projectId) {
+        fail('No project configured. Run `lps project config` first.');
+    }
+    const project = configManager.getProject(projectId);
+    if (!project) {
+        fail(`Project "${projectId}" (from loopress.json) not found. Run \`lps project config\` to configure it.`);
+    }
+    if (!project.apiProjectId) {
+        fail(`Project "${project.name}" is not linked to your Loopress account yet. Run \`lps project push\` first.`);
+    }
+    return { apiProjectId: project.apiProjectId, localConfig, token };
+}

package/dist/lib/validate-local.d.ts

@@ -0,0 +1,10 @@
+export type Problem = {
+    file: string;
+    message: string;
+};
+export type ValidateResult = {
+    checked: number;
+    problems: Problem[];
+    valid: boolean;
+};
+export declare function validateLocal(cwd: string): Promise<ValidateResult>;

package/dist/lib/validate-local.js

@@ -0,0 +1,183 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configManager } from '../config/project-config.manager.js';
+import { parseType } from '../utils/snippet-format.js';
+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 DEFAULT_DIR = {
+    acfDir: 'acf',
+    apiDir: 'api',
+    formDir: 'forms',
+    pageDir: 'pages',
+    seoDir: 'seo',
+    snippetsDir: 'snippets',
+};
+// Inspects the local tracked files under `cwd` without contacting WordPress: JSON files parse
+// and have the right shape, snippet sidecars use a known type, `loopress.json` points at a
+// real project, `composer.json` is well formed. Never throws for a bad file, it collects the
+// problem and moves on.
+export async function validateLocal(cwd) {
+    const problems = [];
+    let checked = 0;
+    const localConfig = await readConfig(cwd, problems);
+    const rootDir = typeof localConfig.rootDir === 'string' ? localConfig.rootDir : '.';
+    const resolve = (key) => {
+        const override = localConfig[key];
+        return join(cwd, rootDir, typeof override === 'string' ? override : DEFAULT_DIR[key]);
+    };
+    checkLoopressJson(localConfig, problems);
+    checked += 1;
+    checked += await checkComposerJson(cwd, problems);
+    for (const key of JSON_RESOURCE_DIRS) {
+        checked += await checkJsonDir(resolve(key), problems);
+    }
+    checked += await checkSnippets(resolve('snippetsDir'), problems);
+    checked += await checkApiDir(resolve('apiDir'), problems);
+    return { checked, problems, valid: problems.length === 0 };
+}
+async function checkApiDir(dir, problems) {
+    const entries = await readdirTolerant(dir, { 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);
+        const content = await readFile(filePath, 'utf8');
+        if (content.trim() === '')
+            problems.push({ file: filePath, message: 'API route file is empty' });
+    }
+    return checked;
+}
+async function checkComposerJson(cwd, problems) {
+    let raw;
+    try {
+        raw = await readFile(join(cwd, 'composer.json'), 'utf8');
+    }
+    catch {
+        // No composer.json is fine, Composer sync is optional.
+        return 0;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        problems.push({ file: 'composer.json', message: `not valid JSON: ${error.message}` });
+        return 1;
+    }
+    for (const key of ['require', 'require-dev']) {
+        const section = parsed[key];
+        if (section !== undefined && (typeof section !== 'object' || section === null || Array.isArray(section))) {
+            problems.push({ file: 'composer.json', message: `"${key}" must be an object` });
+        }
+    }
+    return 1;
+}
+async function checkJsonDir(dir, problems) {
+    const files = (await readdirTolerant(dir)).filter((file) => file.endsWith('.json'));
+    let checked = 0;
+    for (const file of files) {
+        checked += 1;
+        const filePath = join(dir, file);
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(filePath, 'utf8'));
+        }
+        catch (error) {
+            problems.push({ file: filePath, message: `not valid JSON: ${error.message}` });
+            continue;
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            problems.push({ file: filePath, message: 'expected a JSON object' });
+        }
+    }
+    return checked;
+}
+function checkLoopressJson(localConfig, problems) {
+    const { projectId } = localConfig;
+    if (typeof projectId === 'string') {
+        const project = configManager.getProject(projectId);
+        if (!project) {
+            problems.push({
+                file: 'loopress.json',
+                message: `projectId "${projectId}" is not a configured project (run \`lps project config\`)`,
+            });
+        }
+        else if (Object.keys(project.environments).length === 0) {
+            problems.push({ file: 'loopress.json', message: `project "${project.name}" has no environments configured` });
+        }
+    }
+    const { plugins } = localConfig;
+    if (plugins === undefined)
+        return;
+    if (typeof plugins !== 'object' || plugins === null || Array.isArray(plugins)) {
+        problems.push({ file: 'loopress.json', message: '"plugins" must be an object of slug -> version string' });
+        return;
+    }
+    for (const [slug, version] of Object.entries(plugins)) {
+        if (typeof version !== 'string')
+            problems.push({ file: 'loopress.json', message: `plugin "${slug}" must map to a string` });
+    }
+}
+async function checkSnippets(dir, problems) {
+    const listing = await readdirTolerant(dir);
+    if (listing.length === 0)
+        return 0;
+    // loadSnippets reports unreadable files and unparseable sidecars through onSkip.
+    let snippets;
+    try {
+        snippets = await loadSnippets(dir, (message) => {
+            problems.push({ file: dir, message });
+        });
+    }
+    catch (error) {
+        problems.push({ file: dir, message: error.message });
+        return 0;
+    }
+    // loadSnippets coerces an invalid `type` to the extension default rather than failing, so
+    // check the raw sidecars for a bogus enum value the schema would reject.
+    const sidecars = listing.filter((file) => file.endsWith('.json'));
+    for (const file of sidecars) {
+        const filePath = join(dir, file);
+        let meta;
+        try {
+            meta = JSON.parse(await readFile(filePath, 'utf8'));
+        }
+        catch {
+            problems.push({ file: filePath, message: 'not valid JSON' });
+            continue;
+        }
+        if (meta.type !== undefined && parseType(meta.type) === null) {
+            problems.push({ file: filePath, message: `"type": ${JSON.stringify(meta.type)} is not one of css, html, js, php, text` });
+        }
+        if (meta.id !== undefined && !Number.isSafeInteger(meta.id)) {
+            problems.push({ file: filePath, message: '"id" must be an integer' });
+        }
+    }
+    return snippets.length + sidecars.length;
+}
+// Mirrors utils/loopress-config.ts:readLocalConfig, but rooted at an explicit directory rather
+// than process.cwd() so the whole check is driveable from a test without process.chdir(), which
+// vitest's worker threads forbid. A missing file just means "no config".
+async function readConfig(cwd, problems) {
+    let raw;
+    try {
+        raw = await readFile(join(cwd, 'loopress.json'), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        problems.push({ file: 'loopress.json', message: 'loopress.json is not valid JSON. Fix or delete it, then run `lps init` again.' });
+        return {};
+    }
+}

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

@@ -31,14 +31,24 @@ export interface LoopressProjectConfiguration {
      * Directory where custom API route files are read from and written to, relative to rootDir.
      */
     apiDir?: 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;
     /**
      * 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/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;

package/dist/utils/plugin-sync.js

@@ -0,0 +1,31 @@
+// Shared helpers for driving the server-side `loopress/v1/composer/sync` endpoint, used by
+// `lps plugin push`, `lps theme push` and `lps composer push`. The endpoint runs Composer +
+// WPackagist inside WordPress; the CLI only ever sends intent (which slugs at which versions),
+// never a composer.json, so the plugin stays the single authority on that file's shape.
+import { compareVersions } from './version.js';
+// A cold `composer update` on a fresh site easily exceeds the global 30s WpClient timeout.
+export const SYNC_TIMEOUT_MS = 600_000;
+// 422 from the sync endpoint when the intent references a plugin/theme whose folder already
+// exists on the site but isn't tracked in composer.lock (installed by hand through wp-admin).
+// Re-running with --force lets the server remove the folder so Composer can take it over.
+export function parseCollisions(error) {
+    const body = error.cause?.response;
+    if (body?.statusCode !== 422 || !body.body)
+        return null;
+    try {
+        const parsed = JSON.parse(body.body);
+        if (parsed.error === 'unmanaged_plugins_present' && Array.isArray(parsed.collisions)) {
+            return parsed.collisions;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+// Only gates whether a version change needs --force. Unorderable inputs ("latest", a
+// constraint) count as "not a downgrade" so they don't block the push.
+export function isDowngrade(from, to) {
+    const order = compareVersions(to, from);
+    return order !== null && order < 0;
+}

package/dist/utils/plugins.d.ts

@@ -1,13 +1,25 @@
 import { type InstalledPlugin, type PluginManifest, type WpNativePlugin } from '../types/plugin.js';
 export type PluginDiff = {
+    collisions: Array<{
+        installedVersion: string;
+        slug: string;
+    }>;
+    inSync: string[];
     toActivate: Array<{
         file: string;
         slug: string;
     }>;
     toInstall: Array<{
         slug: string;
+        version: string;
+    }>;
+    toPin: Array<{
+        from: string;
+        slug: string;
+        to: string;
     }>;
-    upToDate: string[];
+    toRemove: string[];
+    untrackedActive: string[];
 };
 export type MergeResult = {
     added: string[];
@@ -20,4 +32,5 @@ export type MergeResult = {
 };
 export declare function mergePluginManifest(existing: PluginManifest, incoming: PluginManifest): MergeResult;
 export declare function parseInstalledPlugins(raw: WpNativePlugin[]): InstalledPlugin[];
-export declare function diffPlugins(manifest: PluginManifest, installed: InstalledPlugin[]): PluginDiff;
+export declare function diffPlugins(manifest: PluginManifest, installed: InstalledPlugin[], managedSlugs?: Set<string>): PluginDiff;
+export declare function lockedWpackagistSlugs(composerLock: null | string, kind: 'plugin' | 'theme'): Set<string>;