@loopress/cli 0.21.0 → 0.23.0

package/dist/commands/plugin/add.js

@@ -1,32 +1,42 @@
-import { Args } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { LoopressCommand } from '../../lib/base.js';
 import { writeLocalConfig } from '../../utils/loopress-config.js';
+import { isExactVersion } from '../../utils/version.js';
 export default class Add extends LoopressCommand {
     static args = {
         slug: Args.string({ description: 'Plugin slug on WordPress.org', required: true }),
     };
     static description = 'Add a WordPress.org plugin to loopress.json';
-    static examples = ['$ lps plugin add woocommerce', '$ lps plugin add contact-form-7 --dry-run'];
+    static examples = [
+        '$ lps plugin add woocommerce',
+        '$ lps plugin add woocommerce --version 9.4.2',
+        '$ lps plugin add contact-form-7 --dry-run',
+    ];
     static flags = {
         ...LoopressCommand.dryRunFlag,
+        version: Flags.string({ description: 'Exact version to pin (default: "latest", tracked on every push)' }),
     };
     async run() {
-        const { args } = await this.parse(Add);
+        const { args, flags } = await this.parse(Add);
         const { slug } = args;
+        const version = flags.version ?? 'latest';
+        if (version !== 'latest' && !isExactVersion(version)) {
+            this.error(`--version must be an exact version like 9.4.2, not a Composer constraint. Got "${version}".`);
+        }
         const existing = this.localConfig.plugins ?? {};
-        if (existing[slug] === 'latest') {
-            this.log(`${slug} is already in loopress.json, nothing to do.`);
+        if (existing[slug] === version) {
+            this.log(`${slug} is already pinned to ${version} in loopress.json, nothing to do.`);
             return;
         }
         const isUpdated = existing[slug] !== undefined;
         if (this.dryRun) {
-            this.log(`[dry-run] Would ${isUpdated ? 'update' : 'add'} ${slug} in loopress.json`);
+            this.log(`[dry-run] Would ${isUpdated ? 'update' : 'add'} ${slug} (${version}) in loopress.json`);
             return;
         }
         await writeLocalConfig({
             ...this.localConfig,
-            plugins: { ...existing, [slug]: 'latest' },
+            plugins: { ...existing, [slug]: version },
         });
-        this.log(`${isUpdated ? 'Updated' : 'Added'} ${slug}`);
+        this.log(`${isUpdated ? 'Updated' : 'Added'} ${slug} (${version}). Run \`lps plugin push\` to apply.`);
     }
 }

package/dist/commands/plugin/audit.d.ts

@@ -0,0 +1,30 @@
+import { LoopressCommand } from '../../lib/base.js';
+type Advisory = {
+    cve?: string;
+    fixedIn?: string;
+    score?: number;
+    severity?: string;
+    slug: string;
+    title: string;
+};
+type HealthNote = {
+    message: string;
+    slug: string;
+};
+type AuditResult = {
+    advisories: Advisory[];
+    health: HealthNote[];
+    status: 'clean' | 'issues';
+};
+export default class Audit extends LoopressCommand {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {};
+    run(): Promise<AuditResult>;
+    private auditOne;
+    private fetchHealth;
+    private fetchVulnerabilities;
+    private report;
+}
+export {};

package/dist/commands/plugin/audit.js

@@ -0,0 +1,138 @@
+import got from 'got';
+import { LoopressCommand } from '../../lib/base.js';
+import { compareVersions } from '../../utils/version.js';
+const WPVULN_BASE = 'https://www.wpvulnerability.net/plugin';
+const WPORG_INFO = 'https://api.wordpress.org/plugins/info/1.2/';
+export default class Audit extends LoopressCommand {
+    static description = 'Check the plugins in loopress.json for known vulnerabilities and health issues';
+    static enableJsonFlag = true;
+    static examples = ['$ lps plugin audit'];
+    static flags = {};
+    async run() {
+        const manifest = { ...this.localConfig.plugins };
+        const slugs = Object.keys(manifest);
+        if (slugs.length === 0) {
+            this.log('No plugins in loopress.json to audit.');
+            return { advisories: [], health: [], status: 'clean' };
+        }
+        const advisories = [];
+        const health = [];
+        for (const slug of slugs) {
+            const found = await this.auditOne(slug, manifest[slug]);
+            advisories.push(...found.advisories);
+            health.push(...found.health);
+        }
+        return this.report(advisories, health, slugs.length);
+    }
+    async auditOne(slug, pinned) {
+        const [vulns, info] = await Promise.all([this.fetchVulnerabilities(slug), this.fetchHealth(slug)]);
+        const advisories = vulns
+            .filter((v) => pinned === 'latest' || affects(pinned, v.fixedIn))
+            .map((v) => ({ ...v, slug }));
+        const health = info ? describeHealth(slug, pinned, info) : [];
+        return { advisories, health };
+    }
+    async fetchHealth(slug) {
+        try {
+            const body = await got(WPORG_INFO, {
+                searchParams: { 'action': 'plugin_information', 'request[slug]': slug },
+                timeout: { request: 10_000 },
+            }).json();
+            return typeof body === 'object' && !('error' in body) ? body : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async fetchVulnerabilities(slug) {
+        let body;
+        try {
+            body = await got(`${WPVULN_BASE}/${encodeURIComponent(slug)}/`, {
+                timeout: { request: 10_000 },
+            }).json();
+        }
+        catch (error) {
+            // Never swallow this into an empty list: a clean audit must mean "no advisories found",
+            // not "the advisory service was unreachable". Fail the command instead.
+            throw new Error(`Could not reach the vulnerability database (wpvulnerability.net) for "${slug}": ${error.message}. ` +
+                'Audit aborted so a service outage is not reported as a clean result.', { cause: error });
+        }
+        const list = Array.isArray(body?.data?.vulnerability) ? body.data.vulnerability : [];
+        return list.map((raw) => normalizeAdvisory(raw));
+    }
+    report(advisories, health, count) {
+        if (advisories.length === 0 && health.length === 0) {
+            this.log(`No known vulnerabilities or health issues for ${count} plugin(s).`);
+            return { advisories, health, status: 'clean' };
+        }
+        for (const a of advisories)
+            this.log(`  ⚠ ${a.slug}: ${a.title}${advisoryMeta(a)}`);
+        for (const h of health)
+            this.log(`  · ${h.slug}: ${h.message}`);
+        const noun = advisories.length === 1 ? 'advisory' : 'advisories';
+        this.log(`\n${advisories.length} vulnerability ${noun}, ${health.length} health note(s). ` +
+            'Vulnerability data: wpvulnerability.net.');
+        if (advisories.length > 0)
+            this.exit(1);
+        return { advisories, health, status: 'issues' };
+    }
+}
+function advisoryMeta(a) {
+    const fixed = a.fixedIn ? `fixed in ${a.fixedIn}` : undefined;
+    const parts = [a.severity, a.cve, fixed].filter(Boolean);
+    return parts.length > 0 ? ` (${parts.join(', ')})` : '';
+}
+function normalizeAdvisory(raw) {
+    const cvss = (raw.cvss ?? {});
+    const source = Array.isArray(raw.source) ? raw.source : [];
+    const cve = typeof raw.cve === 'string' ? raw.cve : source.find((s) => s.id?.startsWith('CVE-'))?.id;
+    return {
+        cve,
+        fixedIn: extractFixedIn(raw),
+        score: cvss.score,
+        severity: cvss.severity,
+        title: typeof raw.name === 'string' ? raw.name : 'Unnamed advisory',
+    };
+}
+// wpvulnerability's `impact.software[].versions[]` carries `to_version` / `to_compare`; the
+// first "< X" bound is the version the fix landed in. Best-effort: the shape varies, so a
+// missing bound just means we can't tell and the advisory is reported anyway.
+function extractFixedIn(raw) {
+    const impact = raw.impact;
+    for (const sw of impact?.software ?? []) {
+        for (const v of sw.versions ?? []) {
+            if (v.to_compare === '<' && typeof v.to_version === 'string')
+                return v.to_version;
+        }
+    }
+    return undefined;
+}
+// If we know the fix version, a pin below it is affected. If we can't compare (odd version
+// strings), report it anyway: a false positive is safer than hiding an advisory.
+function affects(pinned, fixedIn) {
+    if (!fixedIn)
+        return true;
+    const order = compareVersions(pinned, fixedIn);
+    return order === null || order < 0;
+}
+function describeHealth(slug, pinned, info) {
+    const notes = [];
+    if (info.closed === true) {
+        notes.push({ message: 'removed from the WordPress.org directory', slug });
+    }
+    const requiresPhp = typeof info.requires_php === 'string' ? info.requires_php : null;
+    if (requiresPhp)
+        notes.push({ message: `requires PHP ${requiresPhp}`, slug });
+    const latest = typeof info.version === 'string' ? info.version : null;
+    const behindLatest = latest ? compareVersions(pinned, latest) : null;
+    if (latest && pinned !== 'latest' && behindLatest !== null && behindLatest < 0) {
+        notes.push({ message: `pinned to ${pinned}, latest is ${latest}`, slug });
+    }
+    const lastUpdated = typeof info.last_updated === 'string' ? info.last_updated : null;
+    if (lastUpdated) {
+        const years = (Date.now() - Date.parse(lastUpdated)) / (365 * 24 * 3600 * 1000);
+        if (years > 2)
+            notes.push({ message: `last updated ${lastUpdated.slice(0, 10)} (possibly abandoned)`, slug });
+    }
+    return notes;
+}

package/dist/commands/plugin/pull.d.ts

@@ -1,7 +1,7 @@
 import { LoopressCommand } from '../../lib/base.js';
 import { type MergeResult } from '../../utils/plugins.js';
 type PullResult = MergeResult & {
-    status: 'dry-run' | 'success';
+    status: 'composer-managed' | 'dry-run' | 'success';
 };
 export default class Pull extends LoopressCommand {
     static description: string;

package/dist/commands/plugin/pull.js

@@ -1,9 +1,10 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { LoopressCommand } from '../../lib/base.js';
-import { getComposerManagedSlugs, readComposerJson } from '../../utils/composer.js';
 import { writeLocalConfig } from '../../utils/loopress-config.js';
 import { mergePluginManifest, parseInstalledPlugins } from '../../utils/plugins.js';
 export default class Pull extends LoopressCommand {
-    static description = 'Pull installed plugins from WordPress into loopress.json';
+    static description = 'Pull installed plugins from WordPress into loopress.json, pinned to their live versions';
     static enableJsonFlag = true;
     static examples = ['$ lps plugin pull', '$ lps plugin pull --dry-run'];
     static flags = {
@@ -11,27 +12,24 @@ export default class Pull extends LoopressCommand {
     };
     async run() {
         const { url } = this.siteConfig;
+        if (existsSync(join(process.cwd(), this.rootDir, 'composer.json'))) {
+            this.warn('This project has a composer.json, which is authoritative for plugins. Run `lps composer pull` instead.');
+            return { added: [], merged: this.localConfig.plugins ?? {}, status: 'composer-managed', updated: [] };
+        }
         this.log(`Pulling plugins from ${url}`);
         const raw = await this.wp.get('wp/v2/plugins');
         const installed = parseInstalledPlugins(raw);
-        const composerJson = await readComposerJson();
-        const composerSlugs = composerJson ? getComposerManagedSlugs(composerJson) : [];
-        const incoming = Object.fromEntries(installed.filter((p) => !composerSlugs.includes(p.slug)).map((p) => [p.slug, 'latest']));
-        if (composerSlugs.length > 0) {
-            const found = installed.filter((p) => composerSlugs.includes(p.slug)).map((p) => p.slug);
-            if (found.length > 0) {
-                this.log(`Skipping ${found.length} Composer-managed ${found.length === 1 ? 'plugin' : 'plugins'}: ${found.join(', ')}`);
-            }
-        }
+        // Pin every plugin to the version actually running on the site. A later `plugin push`
+        // installs exactly this set via Composer + WPackagist; drift only surfaces when the pinned
+        // version and the live version disagree.
+        const incoming = Object.fromEntries(installed.map((p) => [p.slug, p.version]));
         const { added, merged, updated } = mergePluginManifest(this.localConfig.plugins ?? {}, incoming);
         if (this.dryRun) {
             this.log(`[dry-run] Would write ${Object.keys(merged).length} plugins to loopress.json`);
             if (added.length > 0)
                 this.log(`  + ${added.join(', ')}`);
-            if (updated.length > 0) {
-                for (const u of updated)
-                    this.log(`  ~ ${u.slug} (${u.from} → ${u.to})`);
-            }
+            for (const u of updated)
+                this.log(`  ~ ${u.slug} (${u.from} → ${u.to})`);
             return { added, merged, status: 'dry-run', updated };
         }
         await writeLocalConfig({ ...this.localConfig, plugins: merged });

package/dist/commands/plugin/push.d.ts

@@ -2,20 +2,29 @@ import { PushCommand } from '../../lib/push-command.js';
 type PushResult = {
     activated: string[];
     installed: string[];
-    skippedComposerManaged: string[];
-    status: 'dry-run' | 'in-sync' | 'success';
+    pinned: string[];
+    pruned: string[];
+    removed: string[];
+    status: 'composer-managed' | 'dry-run' | 'in-sync' | 'success';
 };
 export default class Push extends PushCommand {
     static description: string;
     static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        prune: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<PushResult>;
-    private activatePlugin;
-    private installPlugin;
-    private performPluginAction;
+    private activate;
+    private confirmRemovals;
+    private deactivate;
+    private deactivateEndangered;
+    private fetchInstanceLock;
+    private guardForce;
+    private result;
+    private sync;
 }
 export {};

package/dist/commands/plugin/push.js

@@ -1,88 +1,199 @@
-import { Listr } from 'listr2';
+import { confirm } from '@inquirer/prompts';
+import { Flags } from '@oclif/core';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isInteractive } from '../../lib/interactive.js';
 import { PushCommand } from '../../lib/push-command.js';
-import { getComposerManagedSlugs, readComposerJson } from '../../utils/composer.js';
-import { diffPlugins, parseInstalledPlugins } from '../../utils/plugins.js';
+import { isNotFoundError } from '../../lib/wp-client.js';
+import { isDowngrade, parseCollisions, SYNC_TIMEOUT_MS } from '../../utils/plugin-sync.js';
+import { diffPlugins, lockedWpackagistSlugs, parseInstalledPlugins } from '../../utils/plugins.js';
+const IN_SYNC = { activated: [], installed: [], pinned: [], pruned: [], removed: [], status: 'in-sync' };
 export default class Push extends PushCommand {
-    static description = 'Push plugins to WordPress to match loopress.json';
+    static description = 'Install plugins on WordPress to match loopress.json, pinned via Composer + WPackagist';
     static enableJsonFlag = true;
-    static examples = ['$ lps plugin push', '$ lps plugin push --dry-run'];
+    static examples = ['$ lps plugin push', '$ lps plugin push --dry-run', '$ lps plugin push --force --prune'];
     static flags = {
         ...PushCommand.dryRunFlag,
         ...PushCommand.yesFlag,
+        force: Flags.boolean({
+            default: false,
+            description: 'Allow downgrades and let Loopress take over plugins installed outside it (replaces their files)',
+        }),
+        prune: Flags.boolean({
+            default: false,
+            description: 'Deactivate plugins that are active on the site but absent from loopress.json',
+        }),
     };
     async run() {
-        const { url } = this.siteConfig;
-        const manifest = this.localConfig.plugins;
-        if (!manifest || Object.keys(manifest).length === 0) {
-            this.error('No plugins found in loopress.json. Run `lps plugin pull` first.');
+        const { flags } = await this.parse(Push);
+        const { force, prune } = flags;
+        if (existsSync(join(process.cwd(), this.rootDir, 'composer.json'))) {
+            this.warn('This project has a composer.json, which is authoritative for plugins. Run `lps composer push` instead.');
+            return { ...IN_SYNC, status: 'composer-managed' };
         }
-        const composerJson = await readComposerJson();
-        const composerSlugs = composerJson ? getComposerManagedSlugs(composerJson) : [];
-        const filteredManifest = Object.fromEntries(Object.entries(manifest).filter(([slug]) => !composerSlugs.includes(slug)));
-        const skippedComposerManaged = composerSlugs.filter((slug) => Object.hasOwn(manifest, slug));
-        if (skippedComposerManaged.length > 0) {
-            this.log(`Skipping ${skippedComposerManaged.length} Composer-managed ${skippedComposerManaged.length === 1 ? 'plugin' : 'plugins'}: ${skippedComposerManaged.join(', ')}`);
-            this.log('Run `lps composer push` to deploy them.');
+        const manifest = this.localConfig.plugins ?? {};
+        if (Object.keys(manifest).length === 0) {
+            this.error('No plugins found in loopress.json. Run `lps plugin pull` or `lps plugin add <slug>` first.');
         }
-        this.log(`Pushing plugins to ${url}`);
+        this.log(`Pushing plugins to ${this.siteConfig.url}`);
         const raw = await this.wp.get('wp/v2/plugins');
         const installed = parseInstalledPlugins(raw);
-        const { toActivate, toInstall } = diffPlugins(filteredManifest, installed);
-        if (toInstall.length === 0 && toActivate.length === 0) {
+        const managed = lockedWpackagistSlugs(await this.fetchInstanceLock(), 'plugin');
+        const diff = diffPlugins(manifest, installed, managed);
+        this.guardForce(diff, force);
+        const toPrune = prune ? diff.untrackedActive : [];
+        // A "latest" pin never shows as drift, but its newest upstream release may have moved
+        // since the last push, so a push must still run `composer update` to pick it up.
+        const hasLatestPin = Object.values(manifest).includes('latest');
+        if (!hasLatestPin && isNoop(diff, toPrune)) {
             this.log('Everything is already in sync.');
-            return { activated: [], installed: [], skippedComposerManaged, status: 'in-sync' };
+            return { ...IN_SYNC };
         }
-        if (toInstall.length > 0) {
-            this.log(`\nTo install (${toInstall.length}):`);
-            for (const a of toInstall)
-                this.log(`  + ${a.slug}`);
+        if (isNoop(diff, toPrune))
+            this.log('Refreshing plugins pinned to "latest" to their newest releases.');
+        logPlan(this, diff, toPrune, force);
+        if (this.dryRun) {
+            return this.result(diff, { includeCollisions: true, pruned: toPrune, removed: diff.toRemove, status: 'dry-run' });
         }
-        if (toActivate.length > 0) {
-            this.log(`\nTo activate (${toActivate.length}):`);
-            for (const a of toActivate)
-                this.log(`  ↑ ${a.slug}`);
-        }
-        const installedSlugs = toInstall.map((a) => a.slug);
-        const activatedSlugs = toActivate.map((a) => a.slug);
-        if (this.dryRun)
-            return { activated: activatedSlugs, installed: installedSlugs, skippedComposerManaged, status: 'dry-run' };
-        // Installing with `status: active` activates in the same call, so installs never need a
-        // separate activation step the way the old custom endpoint's two-step flow did.
-        if (toInstall.length > 0) {
-            await new Listr(toInstall.map((action) => ({
-                task: async (_ctx, task) => this.installPlugin(action.slug, task),
-                title: `Install ${action.slug}`,
-            })), { concurrent: false, exitOnError: false, renderer: this.jsonEnabled() ? 'silent' : 'default' }).run();
+        await this.confirmRemovals(diff.toRemove);
+        const deactivated = await this.deactivateEndangered(installed, diff, force);
+        // Plugins that must end up active: the ones we deactivated for the file swap (minus any
+        // being uninstalled) plus the ones the manifest wants active but that are inactive today.
+        const toReactivate = [...deactivated.filter((p) => !diff.toRemove.includes(p.slug)), ...diff.toActivate];
+        let response;
+        try {
+            response = await this.sync(manifest, force);
         }
-        if (toActivate.length > 0) {
-            await new Listr(toActivate.map((action) => ({
-                task: async (_ctx, task) => this.activatePlugin(action.file, action.slug, task),
-                title: `Activate ${action.slug}`,
-            })), { concurrent: false, exitOnError: false, renderer: this.jsonEnabled() ? 'silent' : 'default' }).run();
+        catch (error) {
+            // The file swap never happened, so restore the plugins we defensively deactivated
+            // instead of leaving the site with them switched off.
+            await this.activate(deactivated.filter((p) => !diff.toRemove.includes(p.slug)));
+            throw error;
         }
-        if (this.failedCount > 0) {
-            this.error(`${this.failedCount} plugin${this.failedCount === 1 ? '' : 's'} failed to install or activate.`);
+        if (toPrune.length > 0) {
+            await this.deactivate(installed.filter((p) => toPrune.includes(p.slug)));
         }
+        await this.activate(toReactivate);
+        if (response.output.trim())
+            this.log(response.output.trim());
+        this.log('Plugins synced.');
         await this.recordSuccess();
-        return { activated: activatedSlugs, installed: installedSlugs, skippedComposerManaged, status: 'success' };
+        return this.result(diff, {
+            activated: toReactivate.map((p) => p.slug),
+            includeCollisions: force,
+            pruned: toPrune,
+            removed: response.removed ?? diff.toRemove,
+            status: 'success',
+        });
+    }
+    async activate(plugins) {
+        for (const plugin of plugins) {
+            this.log(`  ⊙ activating ${plugin.slug}`);
+            await this.wp.put(`wp/v2/plugins/${plugin.file}`, { status: 'active' });
+        }
     }
-    async activatePlugin(file, slug, task) {
-        await this.performPluginAction('activate', slug, async () => this.wp.put(`wp/v2/plugins/${file}`, { status: 'active' }), task);
+    async confirmRemovals(toRemove) {
+        if (toRemove.length === 0 || this.yes || !isInteractive())
+            return;
+        const ok = await confirm({ default: false, message: `Uninstall ${toRemove.join(', ')} from the site?` });
+        if (!ok)
+            this.error('Aborted.');
     }
-    async installPlugin(slug, task) {
-        await this.performPluginAction('install', slug, async () => this.wp.post('wp/v2/plugins', { slug, status: 'active' }), task);
+    async deactivate(plugins) {
+        for (const plugin of plugins) {
+            this.log(`  ⊘ deactivating ${plugin.slug}`);
+            await this.wp.put(`wp/v2/plugins/${plugin.file}`, { status: 'inactive' });
+        }
+    }
+    // Deactivate anything whose folder is about to be deleted or replaced (removed, re-pinned to
+    // a new version, or taken over with --force), so the site does not fatal in the window
+    // between removal and Composer finishing the install. Returns the plugins it switched off so
+    // the caller can switch the still-wanted ones back on.
+    async deactivateEndangered(installed, diff, force) {
+        const endangered = new Set([
+            ...diff.toRemove,
+            ...diff.toPin.map((p) => p.slug),
+            ...(force ? diff.collisions.map((c) => c.slug) : []),
+        ]);
+        const victims = installed.filter((p) => p.active && endangered.has(p.slug));
+        await this.deactivate(victims);
+        return victims;
     }
-    async performPluginAction(verb, slug, request, task) {
+    // The site's live composer.lock tells us which plugins Loopress already manages, so the plan
+    // can preview removals and tell an unmanaged folder (collision) apart from a re-pin. 404 =
+    // nothing pushed yet.
+    async fetchInstanceLock() {
         try {
-            await request();
-            const message = `✓ ${slug} ${verb === 'install' ? 'installed and activated' : 'activated'}`;
-            if (task)
-                task.output = message;
-            else
-                this.log(`  ${message}`);
+            const { composerLock } = await this.wp.get('loopress/v1/composer/lock');
+            return composerLock;
         }
         catch (error) {
-            this.reportTaskFailure(`Failed to ${verb} ${slug}: ${error.message}`, error, task);
+            if (isNotFoundError(error))
+                return null;
+            throw error;
+        }
+    }
+    guardForce(diff, force) {
+        if (force)
+            return;
+        if (diff.collisions.length > 0) {
+            const list = diff.collisions.map((c) => `${c.slug} (${c.installedVersion})`).join(', ');
+            this.error(`${diff.collisions.length} plugin(s) are already installed outside Loopress: ${list}. ` +
+                'Re-run with --force to let Loopress manage them (this replaces their files with the WPackagist build, ' +
+                'local modifications are lost), or remove them from loopress.json.');
+        }
+        const downgrades = diff.toPin.filter((p) => isDowngrade(p.from, p.to));
+        if (downgrades.length > 0) {
+            const list = downgrades.map((p) => `${p.slug} ${p.from} to ${p.to}`).join(', ');
+            this.error(`Refusing to downgrade: ${list}. A downgrade only replaces plugin files, it does not undo database ` +
+                'migrations the newer version ran, which can break the site. Re-run with --force, or bump the version in loopress.json.');
         }
     }
+    result(diff, opts) {
+        const collisionSlugs = opts.includeCollisions ? diff.collisions.map((c) => c.slug) : [];
+        return {
+            activated: opts.activated ?? diff.toActivate.map((a) => a.slug),
+            installed: [...diff.toInstall.map((a) => a.slug), ...collisionSlugs],
+            pinned: diff.toPin.map((p) => p.slug),
+            pruned: opts.pruned,
+            removed: opts.removed,
+            status: opts.status,
+        };
+    }
+    async sync(manifest, force) {
+        try {
+            return await this.wp.post('loopress/v1/composer/sync', { force, intent: { plugins: manifest }, lock: null }, { timeoutMs: SYNC_TIMEOUT_MS });
+        }
+        catch (error) {
+            const collisions = parseCollisions(error);
+            if (collisions) {
+                this.error(`The site rejected the push: ${collisions.map((c) => c.slug).join(', ')} installed outside Loopress. Re-run with --force.`);
+            }
+            throw error;
+        }
+    }
+}
+function isNoop(diff, toPrune) {
+    return (diff.toInstall.length === 0 &&
+        diff.toPin.length === 0 &&
+        diff.toActivate.length === 0 &&
+        diff.toRemove.length === 0 &&
+        diff.collisions.length === 0 &&
+        toPrune.length === 0);
+}
+function logPlan(cmd, diff, prune, force) {
+    const section = (label, lines) => {
+        if (lines.length === 0)
+            return;
+        cmd.log(`\n${label} (${lines.length}):`);
+        for (const line of lines)
+            cmd.log(`  ${line}`);
+    };
+    section('To install', diff.toInstall.map((a) => `+ ${a.slug} ${a.version}`));
+    if (force)
+        section('To take over', diff.collisions.map((c) => `! ${c.slug} (installed outside Loopress)`));
+    section('To re-pin', diff.toPin.map((p) => `~ ${p.slug} ${p.from} to ${p.to}`));
+    section('To activate', diff.toActivate.map((a) => `↑ ${a.slug}`));
+    section('To uninstall', diff.toRemove.map((s) => `- ${s}`));
+    section('To deactivate (--prune)', prune.map((s) => `⊘ ${s}`));
 }

package/dist/commands/plugin/status.d.ts

@@ -0,0 +1,22 @@
+import { LoopressCommand } from '../../lib/base.js';
+type StatusResult = {
+    drift: boolean;
+    inactive: string[];
+    missing: string[];
+    status: 'composer-managed' | 'drift' | 'in-sync';
+    untrackedActive: string[];
+    wrongVersion: Array<{
+        live: string;
+        pinned: string;
+        slug: string;
+    }>;
+};
+export default class Status extends LoopressCommand {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {};
+    run(): Promise<StatusResult>;
+    private fetchInstanceLock;
+}
+export {};