@loopress/cli 0.33.0 → 0.35.0

package/dist/commands/plugin/outdated.js

@@ -0,0 +1,67 @@
+import { LoopressCommand } from '../../lib/base.js';
+import { withSpinner } from '../../lib/spinner.js';
+import { pinVersion } from '../../types/plugin.js';
+import { compareVersions, versionJump } from '../../utils/version.js';
+import { requestPluginInfo } from '../../utils/wporg.js';
+export default class Outdated extends LoopressCommand {
+    static description = 'Compare the plugins in loopress.json to the latest WordPress.org versions (exits 1 when one is behind or cannot be checked)';
+    static enableJsonFlag = true;
+    static examples = ['$ lps plugin outdated', '$ lps plugin outdated --json'];
+    static flags = {};
+    async run() {
+        const entries = Object.entries(this.localConfig.plugins ?? {});
+        if (entries.length === 0) {
+            this.log('No plugins in loopress.json.');
+            return { outdated: 0, plugins: [] };
+        }
+        const plugins = await withSpinner('Checking plugins', async () => Promise.all(entries.map(async ([slug, pin]) => checkPlugin(slug, pinVersion(pin)))));
+        const outdated = plugins.filter((p) => p.status === 'outdated').length;
+        this.printTable(plugins);
+        const failed = plugins.filter((p) => ['closed', 'error'].includes(p.status)).length;
+        if (outdated > 0)
+            this.log(`\n${outdated} plugin(s) behind WordPress.org.`);
+        if (failed > 0)
+            this.log(`\n${failed} plugin(s) closed on WordPress.org or could not be checked.`);
+        if (outdated === 0 && failed === 0)
+            this.log('\nAll plugins are up to date.');
+        // exit() throws before oclif prints the --json result, which a CI reading it needs most here.
+        if (outdated > 0 || failed > 0) {
+            if (this.jsonEnabled())
+                process.exitCode = 1;
+            else
+                this.exit(1);
+        }
+        return { outdated, plugins };
+    }
+    printTable(plugins) {
+        const rows = [
+            ['PLUGIN', 'CURRENT', 'LATEST', 'JUMP'],
+            ...plugins.map((p) => [p.slug, p.current, p.latest ?? '-', p.jump ?? (['closed', 'error', 'unknown'].includes(p.status) ? p.status : '-')]),
+        ];
+        const widths = [0, 1, 2, 3].map((i) => Math.max(...rows.map((r) => (r[i] ?? '').length)));
+        for (const row of rows)
+            this.log(row.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join('  ').trimEnd());
+    }
+}
+async function checkPlugin(slug, current) {
+    let info;
+    try {
+        info = await requestPluginInfo(slug);
+    }
+    catch {
+        return { current, jump: null, latest: null, slug, status: 'error' };
+    }
+    if (info?.error === 'closed')
+        return { current, jump: null, latest: null, slug, status: 'closed' };
+    const latest = typeof info?.version === 'string' ? info.version : null;
+    // Not on WordPress.org (zip, premium), unknown. An unreachable API is an error.
+    if (!latest)
+        return { current, jump: null, latest: null, slug, status: 'unknown' };
+    // "latest" always installs the newest release: it is never behind.
+    const jump = versionJump(current, latest);
+    if (jump)
+        return { current, jump, latest, slug, status: 'outdated' };
+    // Equal or ahead is current; a pin that can't be ordered at all is unknown.
+    const comparable = current === 'latest' || compareVersions(current, latest) !== null;
+    return { current, jump: null, latest, slug, status: comparable ? 'current' : 'unknown' };
+}

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

@@ -24,10 +24,11 @@ export default class Push extends PushCommand {
     private deactivate;
     private deactivateEndangered;
     private fetchInstanceLock;
-    private filesForNewlyInstalled;
     private guardForce;
+    private installedBySync;
     private loadSource;
     private logStillInactive;
+    private removeStaleCopies;
     private result;
     private sync;
 }

package/dist/commands/plugin/push.js

@@ -3,12 +3,13 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { confirmUninstall } from '../../lib/interactive.js';
+import { causeOf, isRecord } from '../../lib/narrow.js';
 import { PushCommand } from '../../lib/push-command.js';
-import { isLocalEnvironment, isNotFoundError } from '../../lib/wp-client.js';
-import { pinActive, pinVersion, pinVersions, } from '../../types/plugin.js';
+import { isLocalEnvironment, isNotFoundError, parseBody, responseOf } from '../../lib/wp-client.js';
+import { pinActive, pinProblem, pinVersion, pinVersions, } from '../../types/plugin.js';
 import { parseComposerJson, requireToInstall, toIntent, wpackagistRequire } from '../../utils/composer.js';
 import { isDowngrade, parseCollisions, SYNC_TIMEOUT_MS, } from '../../utils/plugin-sync.js';
-import { diffPlugins, lockedWpackagistSlugs, parseInstalledPlugins } from '../../utils/plugins.js';
+import { diffPlugins, lockedWpackagistSlugs, parseInstalledPlugins, preferredCopy, } from '../../utils/plugins.js';
 import { isExactVersion } from '../../utils/version.js';
 const IN_SYNC = {
     activated: [],
@@ -64,6 +65,9 @@ export default class Push extends PushCommand {
         if (!hasFloatingPin && isNoop(diff, toPrune)) {
             this.log('Everything is already in sync.');
             this.logStillInactive(skippedActivations);
+            // The inventory still matters to the console when nothing had to change.
+            if (!this.dryRun)
+                await this.recordDeployment('success');
             return { ...IN_SYNC };
         }
         if (isNoop(diff, toPrune))
@@ -74,8 +78,9 @@ export default class Push extends PushCommand {
         }
         if (!(await confirmUninstall(diff.toRemove, this.yes)))
             this.error('Aborted.');
+        const switchedOff = await this.deactivateEndangered(installed, diff, force);
         // Plugins switched off for the file swap come back on, unless loopress.json wants them inactive.
-        const deactivated = (await this.deactivateEndangered(installed, diff, force)).filter((p) => !diff.toRemove.includes(p.slug) && (fromComposer || pinActive(source.manifest[p.slug])));
+        const deactivated = switchedOff.filter((p) => !diff.toRemove.includes(p.slug) && (fromComposer || pinActive(source.manifest[p.slug])));
         let response;
         try {
             response = await this.sync(source.intent, force);
@@ -86,9 +91,14 @@ export default class Push extends PushCommand {
             await this.activate(deactivated);
             throw error;
         }
-        const activateNew = (slug) => (fromComposer ? activate : pinActive(source.manifest[slug]));
-        const newlyInstalled = await this.filesForNewlyInstalled(diff.toInstall);
-        const toActivate = [...deactivated, ...diff.toActivate, ...newlyInstalled.filter((p) => activateNew(p.slug))];
+        const wasActive = new Set(switchedOff.map((p) => p.slug));
+        const activateNew = (slug) => fromComposer ? activate || wasActive.has(slug) : pinActive(source.manifest[slug]);
+        const { newlyInstalled, takenOver } = await this.installedBySync(installed, diff, force);
+        const toActivate = [
+            ...deactivated.filter((p) => takenOver.every((t) => t.slug !== p.slug)),
+            ...diff.toActivate,
+            ...[...newlyInstalled, ...takenOver].filter((p) => activateNew(p.slug)),
+        ];
         const toDeactivate = [...diff.toDeactivate, ...installed.filter((p) => toPrune.includes(p.slug))];
         await this.deactivate(toDeactivate);
         await this.activate(toActivate);
@@ -105,10 +115,33 @@ export default class Push extends PushCommand {
             status: 'success',
         });
     }
+    // WordPress refuses to activate a plugin whose `Requires Plugins` are inactive, and loopress.json
+    // has no dependency order (dokan-lite sorts before woocommerce). A refused plugin is retried
+    // after the others, until a round activates nothing.
     async activate(plugins) {
-        for (const plugin of plugins) {
-            this.log(`  ⊙ activating ${plugin.slug}`);
-            await this.wp.put(`wp/v2/plugins/${plugin.file}`, { status: 'active' });
+        let pending = plugins;
+        while (pending.length > 0) {
+            const blocked = [];
+            let missing = [];
+            for (const plugin of pending) {
+                this.log(`  ⊙ activating ${plugin.slug}`);
+                try {
+                    await this.wp.put(`wp/v2/plugins/${plugin.file}`, { status: 'active' });
+                }
+                catch (error) {
+                    const notInstalled = missingDependencies(error);
+                    if (!notInstalled)
+                        throw error;
+                    blocked.push(plugin);
+                    missing = [...missing, ...notInstalled];
+                }
+            }
+            if (blocked.length === pending.length) {
+                const hint = missing.length > 0 ? ` Not installed: ${[...new Set(missing)].join(', ')}.` : '';
+                this.error(`Could not activate ${blocked.map((p) => p.slug).join(', ')}: WordPress reports required plugins missing or inactive.${hint} ` +
+                    'Add them with `lps plugin add <slug>`, then push again.');
+            }
+            pending = blocked;
         }
     }
     async deactivate(plugins) {
@@ -145,19 +178,6 @@ export default class Push extends PushCommand {
             throw error;
         }
     }
-    // toInstall entries carry no `file`: the plugin didn't exist on the site at diff time, so its
-    // WordPress core plugin id (folder/main-file.php) is only knowable after sync() has actually
-    // installed it. Refetch to get it, then activate like everything else.
-    async filesForNewlyInstalled(toInstall) {
-        if (toInstall.length === 0)
-            return [];
-        const installedAfterSync = parseInstalledPlugins(await this.wp.get('wp/v2/plugins'));
-        const fileBySlug = new Map(installedAfterSync.map((p) => [p.slug, p.file]));
-        return toInstall.flatMap(({ slug }) => {
-            const file = fileBySlug.get(slug);
-            return file ? [{ file, slug }] : [];
-        });
-    }
     guardForce(diff, force, file) {
         if (force)
             return;
@@ -174,6 +194,21 @@ export default class Push extends PushCommand {
                 `migrations the newer version ran, which can break the site. Re-run with --force, or bump the version in ${file}.`);
         }
     }
+    // New and taken-over plugins only get their final WordPress id (folder/main-file) once
+    // sync() has installed them: read it from the site. A taken-over plugin is activated from
+    // the folder Composer installed, with no stale copy left beside it.
+    async installedBySync(installed, diff, force) {
+        const collisions = force ? diff.collisions.map((c) => c.slug) : [];
+        if (diff.toInstall.length === 0 && collisions.length === 0)
+            return { newlyInstalled: [], takenOver: [] };
+        const afterSync = parseInstalledPlugins(await this.wp.get('wp/v2/plugins'));
+        const takenOver = filesFor(collisions, afterSync);
+        const kept = await this.removeStaleCopies(installed, afterSync, takenOver);
+        return {
+            newlyInstalled: filesFor(diff.toInstall.map((p) => p.slug), afterSync),
+            takenOver: takenOver.filter((p) => !kept.includes(p.slug)),
+        };
+    }
     async loadSource(activate) {
         const composerJsonPath = join(process.cwd(), this.rootDir, 'composer.json');
         if (existsSync(composerJsonPath)) {
@@ -193,6 +228,10 @@ export default class Push extends PushCommand {
         if (Object.keys(manifest).length === 0) {
             this.error('No plugins found in loopress.json. Run `lps plugin pull` or `lps plugin add <slug>` first.');
         }
+        // A mistyped key (`activate`) would otherwise push the plugin with the default state.
+        const problems = Object.entries(manifest).flatMap(([slug, pin]) => pinProblem(slug, pin) ?? []);
+        if (problems.length > 0)
+            this.error(`Invalid loopress.json: ${problems.join('; ')}. Fix it, then push again.`);
         return {
             file: 'loopress.json',
             intent: { plugins: pinVersions(manifest) },
@@ -207,6 +246,34 @@ export default class Push extends PushCommand {
         this.log(`${plugins.length} plugin(s) from composer.json are inactive: ${plugins.map((p) => p.slug).join(', ')}.`);
         this.log('Re-run with --activate to activate them, or activate them in wp-admin.');
     }
+    // A takeover installs `wp-content/plugins/<slug>/`, but the plugin it replaces may live
+    // elsewhere: core's Hello Dolly is `hello.php`, which the site lists under the slug
+    // `hello-dolly`. Composer leaves that file in place, and both copies declare the same
+    // functions, so activating them together would fatal: delete the stale copy, as --force says.
+    // Returns the slugs whose stale copy could not be deleted: the caller must not activate
+    // their replacement beside it. Copies the sync already removed are skipped, and a failed
+    // deletion does not stop the others or the activations.
+    async removeStaleCopies(installed, afterSync, managedCopies) {
+        const replaced = installed.flatMap((old) => {
+            const copy = managedCopies.find((c) => c.slug === old.slug && c.file !== old.file);
+            return copy && afterSync.some((a) => a.file === old.file) ? [{ copy, old }] : [];
+        });
+        const kept = [];
+        for (const { copy, old } of replaced) {
+            this.log(`  ✕ removing ${old.file} (replaced by ${copy.file})`);
+            try {
+                // Deactivated before the sync if it was active (deactivateEndangered): WordPress
+                // refuses to delete an active plugin.
+                await this.wp.delete(`wp/v2/plugins/${old.file}`);
+            }
+            catch (error) {
+                kept.push(old.slug);
+                this.warn(`Could not delete ${old.file}: ${error instanceof Error ? error.message : String(error)}. ` +
+                    `${copy.file} stays inactive until it is deleted: remove ${old.file} in wp-admin, then activate ${copy.slug}.`);
+            }
+        }
+        return kept;
+    }
     result(diff, opts) {
         const collisionSlugs = opts.includeCollisions ? diff.collisions.map((c) => c.slug) : [];
         return {
@@ -232,6 +299,25 @@ export default class Push extends PushCommand {
         }
     }
 }
+// The dependency slugs not installed at all when WordPress refused an activation over unmet
+// `Requires Plugins` (empty when they are only inactive), or null for any other error. The REST
+// controller adds `{status: 500}` as the error data, which pushes activate_plugin()'s own data
+// (`{not_installed, inactive}`) into `additional_data`.
+function missingDependencies(error) {
+    const body = parseBody(responseOf(causeOf(error)).body);
+    if (body.code !== 'plugin_missing_dependencies')
+        return null;
+    const data = [body.data, ...(Array.isArray(body.additional_data) ? body.additional_data : [])];
+    return data.flatMap((d) => (isRecord(d) && isRecord(d.not_installed) ? Object.keys(d.not_installed) : []));
+}
+// The WordPress plugin id of each slug, read after sync() has installed it: a plugin the diff
+// saw as missing (or as an unmanaged copy) has no id, or the wrong one, before that.
+function filesFor(slugs, installed) {
+    return slugs.flatMap((slug) => {
+        const match = preferredCopy(installed.filter((p) => p.slug === slug), slug);
+        return match ? [{ file: match.file, slug }] : [];
+    });
+}
 function isNoop(diff, toPrune) {
     return (diff.toInstall.length === 0 &&
         diff.toPin.length === 0 &&

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

@@ -0,0 +1,36 @@
+import { LoopressCommand } from '../../lib/base.js';
+import { type VersionJump } from '../../utils/version.js';
+export type PluginChange = {
+    from: string;
+    jump: VersionJump;
+    slug: string;
+    to: string;
+};
+export type SkippedPlugin = {
+    reason: 'current' | 'error' | 'latest' | 'unknown';
+    slug: string;
+    version: string;
+};
+type UpdateResult = {
+    changes: PluginChange[];
+    skipped: SkippedPlugin[];
+};
+type Cap = 'minor' | 'patch' | undefined;
+export default class Update extends LoopressCommand {
+    static args: {
+        slug: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        minor: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        patch: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static strict: boolean;
+    run(): Promise<UpdateResult>;
+    private write;
+}
+export declare function pickUpdate(current: string, latest: string, versions: unknown, cap: Cap): null | string;
+export {};

package/dist/commands/plugin/update.js

@@ -0,0 +1,121 @@
+import { Args, Flags } from '@oclif/core';
+import { LoopressCommand } from '../../lib/base.js';
+import { withSpinner } from '../../lib/spinner.js';
+import { pinVersion } from '../../types/plugin.js';
+import { writeLocalConfig } from '../../utils/loopress-config.js';
+import { compareVersions, isExactVersion, versionJump } from '../../utils/version.js';
+import { requestPluginInfo } from '../../utils/wporg.js';
+export default class Update extends LoopressCommand {
+    static args = {
+        slug: Args.string({ description: 'Plugin slug(s) in loopress.json to update (default: all of them)' }),
+    };
+    static description = 'Rewrite plugin versions in loopress.json to the latest WordPress.org releases (loopress.json only, run `lps plugin push` to apply)';
+    static enableJsonFlag = true;
+    static examples = [
+        '$ lps plugin update',
+        '$ lps plugin update woocommerce akismet',
+        '$ lps plugin update --minor',
+        '$ lps plugin update --patch --json',
+    ];
+    static flags = {
+        ...LoopressCommand.dryRunFlag,
+        minor: Flags.boolean({ description: 'Stay on the current major version (minor and patch releases only)', exclusive: ['patch'] }),
+        patch: Flags.boolean({ description: 'Stay on the current minor version (patch releases only)', exclusive: ['minor'] }),
+    };
+    static strict = false;
+    async run() {
+        const { argv, flags } = await this.parse(Update);
+        const pins = this.localConfig.plugins ?? {};
+        const requested = [...new Set(argv.map(String))];
+        const missing = requested.filter((slug) => !Object.hasOwn(pins, slug));
+        if (missing.length > 0)
+            this.error(`Not in loopress.json: ${missing.join(', ')}. Add it with \`lps plugin add\`.`);
+        const targets = Object.entries(pins).filter(([slug]) => requested.length === 0 || requested.includes(slug));
+        if (targets.length === 0) {
+            this.log('No plugins in loopress.json.');
+            return { changes: [], skipped: [] };
+        }
+        const results = await withSpinner('Checking plugins', async () => Promise.all(targets.map(async ([slug, pin]) => resolveUpdate(slug, pinVersion(pin), capOf(flags)))));
+        const changes = results.filter((r) => 'to' in r);
+        const skipped = results.filter((r) => 'reason' in r);
+        for (const c of changes)
+            this.log(`${this.dryRun ? '[dry-run] ' : ''}${c.slug}  ${c.from} -> ${c.to}  (${c.jump})`);
+        const unchecked = skipped.some((s) => s.reason === 'unknown' || s.reason === 'error');
+        if (!unchecked && changes.length === 0)
+            this.log('Every plugin is already at the newest version allowed.');
+        else if (changes.length > 0 && !this.dryRun)
+            await this.write(changes);
+        const failed = skipped.filter((s) => s.reason === 'error').map((s) => s.slug);
+        if (failed.length > 0) {
+            this.warn(`Could not check ${failed.join(', ')} (WordPress.org unreachable).`);
+            // Same as `plugin outdated`: exit() would throw before oclif prints the --json result.
+            if (this.jsonEnabled())
+                process.exitCode = 1;
+            else
+                this.exit(1);
+        }
+        return { changes, skipped };
+    }
+    async write(changes) {
+        const plugins = { ...this.localConfig.plugins };
+        for (const { slug, to } of changes) {
+            const pin = plugins[slug];
+            // An object pin keeps its other keys (an inactive plugin stays inactive).
+            plugins[slug] = typeof pin === 'object' ? { ...pin, version: to } : to;
+        }
+        await writeLocalConfig({ ...this.localConfig, plugins });
+        this.log(`\nUpdated ${changes.length} plugin(s) in loopress.json. Run \`lps plugin push\` to apply.`);
+    }
+}
+function capOf(flags) {
+    if (flags.patch)
+        return 'patch';
+    return flags.minor ? 'minor' : undefined;
+}
+async function resolveUpdate(slug, current, cap) {
+    if (current === 'latest')
+        return { reason: 'latest', slug, version: current };
+    // A wildcard or range constraint (9.4.x) is not an exact pin: rewriting it would widen it.
+    if (!isExactVersion(current))
+        return { reason: 'unknown', slug, version: current };
+    let info;
+    try {
+        info = await requestPluginInfo(slug, { versions: cap !== undefined });
+    }
+    catch {
+        return { reason: 'error', slug, version: current };
+    }
+    const latest = typeof info?.version === 'string' ? info.version : null;
+    if (!latest || compareVersions(current, latest) === null)
+        return { reason: 'unknown', slug, version: current };
+    // A cap needs the release list: without it an eligible release could be missed silently.
+    const listed = info?.versions;
+    if (cap !== undefined && (typeof listed !== 'object' || listed === null || Object.keys(listed).length === 0)) {
+        return { reason: 'unknown', slug, version: current };
+    }
+    const to = pickUpdate(current, latest, info?.versions, cap);
+    const jump = to ? versionJump(current, to) : null;
+    return to && jump ? { from: current, jump, slug, to } : { reason: 'current', slug, version: current };
+}
+// The version `current` should move to: `latest` without a cap, otherwise the newest stable
+// release from WordPress.org's version list that keeps the major (--minor) or the major and
+// minor (--patch). Null when nothing newer qualifies.
+export function pickUpdate(current, latest, versions, cap) {
+    if (cap === undefined)
+        return versionJump(current, latest) ? latest : null;
+    const listed = typeof versions === 'object' && versions !== null ? Object.keys(versions) : [];
+    let best = null;
+    for (const candidate of [...listed, latest]) {
+        // Skips "trunk", prereleases and anything beyond the advertised latest release.
+        if (!/^\d+(?:\.\d+){0,3}$/.test(candidate) || !isExactVersion(candidate))
+            continue;
+        if ((compareVersions(candidate, latest) ?? 1) > 0)
+            continue;
+        const jump = versionJump(current, candidate);
+        if (!jump || jump === 'major' || (cap === 'patch' && jump === 'minor'))
+            continue;
+        if (best === null || (compareVersions(candidate, best) ?? 0) > 0)
+            best = candidate;
+    }
+    return best;
+}

package/dist/commands/project/config.js

@@ -94,7 +94,6 @@ export default class Config extends Command {
         }
         this.log(`✓ "${projectName}/${envName}" configured`);
         await this.maybeBootstrapLoopressFull(env);
-        this.log('→ Run `lps project switch` to change the active project or environment');
     }
     async maybeBootstrapLoopressFull(env) {
         const { name, token, url } = env;

package/dist/commands/promote.d.ts

@@ -14,6 +14,7 @@ export default class Promote extends Command {
     static examples: string[];
     static flags: {
         overwrite: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'skip-unsupported': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/promote.js

@@ -20,15 +20,17 @@ export default class Promote extends Command {
     };
     static description = 'Copy every tracked resource from one environment to another by pulling from <from> then pushing to <to>. Local tracked files are overwritten with <from> in the process. With --dry-run, <from> is pulled into a throwaway copy of the project instead, and the push is only previewed.';
     static enableJsonFlag = true;
-    static examples = ['$ lps promote staging production', '$ lps promote production staging --dry-run'];
+    static examples = ['$ lps promote staging production', '$ lps promote production staging --dry-run', '$ lps promote staging production --skip-unsupported'];
     static flags = {
         ...LoopressCommand.dryRunFlag,
         ...LoopressCommand.yesFlag,
+        ...LoopressCommand.skipUnsupportedFlag,
         overwrite: PushCommand.baseFlags.overwrite,
     };
     async run() {
         const { args, flags } = await this.parse(Promote);
         const { overwrite, yes } = flags;
+        const skipUnsupported = flags['skip-unsupported'];
         const dryRun = flags['dry-run'];
         const { environments, projectName } = await this.resolveProject();
         const from = this.requireEnvironment(environments, projectName, args.from);
@@ -52,7 +54,7 @@ export default class Promote extends Command {
         try {
             this.log(`\n=== Pulling from ${from.name} (${from.url}) ===`);
             try {
-                await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand('pull', this.delegateArgv(from.name, false)));
+                await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand('pull', this.delegateArgv(from.name, false, skipUnsupported)));
             }
             catch (error) {
                 // A partial pull must never be pushed onward: stop before touching <to>.
@@ -61,7 +63,7 @@ export default class Promote extends Command {
                 this.error(`Pull from ${from.name} failed, nothing was pushed to ${to.name}.${filesNote} ${errorMessage(error)}`);
             }
             this.log(`\n=== Pushing to ${to.name} (${to.url}) ===`);
-            await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand('push', [...this.delegateArgv(to.name, dryRun), ...(overwrite ? ['--overwrite'] : [])]));
+            await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand('push', [...this.delegateArgv(to.name, dryRun, skipUnsupported), ...(overwrite ? ['--overwrite'] : [])]));
         }
         finally {
             if (scratch) {
@@ -114,8 +116,10 @@ export default class Promote extends Command {
     // `--yes` is always forwarded: confirmPromotion above already gathered intent once, so the
     // delegated `pull` and `push` must not prompt again (push would otherwise re-run its own
     // production guard, and pull its orphan-deletion prompt).
-    delegateArgv(env, dryRun) {
+    delegateArgv(env, dryRun, skipUnsupported) {
         const argv = ['--env', env, '--yes'];
+        if (skipUnsupported)
+            argv.push('--skip-unsupported');
         if (dryRun)
             argv.push('--dry-run');
         return argv;

package/dist/commands/pull.d.ts

@@ -2,6 +2,7 @@ import { LoopressCommand } from '../lib/base.js';
 type PullTargetResult = {
     error?: string;
     label: string;
+    reason?: string;
     status: 'failed' | 'pulled' | 'skipped';
 };
 type PullResult = {
@@ -12,14 +13,18 @@ export default class Pull extends LoopressCommand {
     static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
+        'skip-unsupported': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     private failedCount;
+    private skipUnsupported;
+    private readonly unsupported;
     run(): Promise<PullResult>;
     private buildArgv;
     private globalStylesSkipNote;
     private projectUses;
     private unavailable;
+    private warnUnsupported;
 }
 export {};

package/dist/commands/pull.js

@@ -1,5 +1,6 @@
 import { LoopressCommand } from '../lib/base.js';
-import { missingIntegration, missingModule } from '../lib/capabilities.js';
+import { integrationFix, missingIntegration, missingModule } from '../lib/capabilities.js';
+import { declaredPlugins } from '../lib/declared-plugins.js';
 import { stdoutToStderr } from '../lib/json-delegation.js';
 import { errorMessage } from '../lib/narrow.js';
 import { pluralize } from '../utils/pluralize.js';
@@ -42,9 +43,15 @@ export default class Pull extends LoopressCommand {
     static flags = {
         ...LoopressCommand.dryRunFlag,
         ...LoopressCommand.yesFlag,
+        ...LoopressCommand.skipUnsupportedFlag,
     };
     failedCount = 0;
+    skipUnsupported = false;
+    // What --skip-unsupported held back: the target and why, for the final warning.
+    unsupported = [];
     async run() {
+        const { flags } = await this.parse(Pull);
+        this.skipUnsupported = flags['skip-unsupported'];
         const results = [];
         const capabilities = await this.capabilities();
         for (const target of PULL_TARGETS) {
@@ -73,12 +80,14 @@ export default class Pull extends LoopressCommand {
             }
         }
         if (this.failedCount > 0) {
+            await this.warnUnsupported();
             // Each failure's own reason, not just the count: under --json the per-resource lines above
             // never reach stdout, and this message is all an MCP caller or a script gets to see.
             const failures = results.filter((result) => result.status === 'failed').map((result) => `${result.label}: ${result.error}`);
             this.error(`${pluralize(this.failedCount, 'resource')} failed to pull. ${failures.join('; ')}`);
         }
         this.log('\nAll resources pulled.');
+        await this.warnUnsupported();
         return { results };
     }
     // `--yes` is forwarded only when the user passed it and the target accepts it: unlike
@@ -116,9 +125,25 @@ export default class Pull extends LoopressCommand {
             this.log(`\n→ ${target.label}: ${missing.needsFull ? missing.reason : 'not configured'}, skipped`);
             return { label: target.label, status: 'skipped' };
         }
+        if (this.skipUnsupported) {
+            this.unsupported.push({ label: target.label, missing });
+            this.log(`\n→ ${target.label}: ${missing.reason}, skipped (--skip-unsupported)`);
+            return { label: target.label, reason: `${missing.reason} on ${this.siteConfig.name}`, status: 'skipped' };
+        }
         this.failedCount++;
         const error = `${missing.reason} on ${this.siteConfig.name}`;
         this.log(`\n✗ ${target.label} failed: ${error}`);
         return { error, label: target.label, status: 'failed' };
     }
+    async warnUnsupported() {
+        if (this.unsupported.length === 0)
+            return;
+        const declared = await declaredPlugins({ localConfig: this.localConfig, rootDir: this.rootDir, siteName: this.siteConfig.name });
+        const lines = this.unsupported.map(({ label, missing }) => {
+            const fix = integrationFix(missing, declared);
+            const fixSentence = fix ? ` ${fix}.` : '';
+            return `${label}: ${missing.reason} on ${this.siteConfig.name}.${fixSentence}`;
+        });
+        this.warn(`Skipped with --skip-unsupported, this site can't hold them:\n  ${lines.join('\n  ')}`);
+    }
 }

package/dist/commands/push.d.ts

@@ -2,6 +2,7 @@ import { LoopressCommand } from '../lib/base.js';
 type PushTargetResult = {
     error?: string;
     label: string;
+    reason?: string;
     result?: unknown;
     status: 'failed' | 'pushed' | 'skipped';
 };
@@ -14,16 +15,24 @@ export default class Push extends LoopressCommand {
     static examples: string[];
     static flags: {
         overwrite: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'skip-unsupported': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        only: ReturnType<typeof import("@oclif/core/flags").string>;
+        skip: ReturnType<typeof import("@oclif/core/flags").string>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
+    private skipUnsupported;
+    private readonly unsupported;
     run(): Promise<PushResult>;
     private applySiteSteps;
     private buildArgv;
     private composerJsonPath;
     private declaredPlugins;
+    private doneMessage;
     private globalStylesSkipNote;
     private guardProductionPush;
     private skippedTargets;
+    private unsupportedLine;
+    private warnUnsupported;
 }
 export {};