@loopress/cli 0.32.2 → 0.34.0

package/dist/commands/promote.js

@@ -8,7 +8,9 @@ import { configManager } from '../config/project-config.manager.js';
 import { LoopressCommand } from '../lib/base.js';
 import { isInteractive } from '../lib/interactive.js';
 import { stdoutToStderr } from '../lib/json-delegation.js';
+import { errorMessage } from '../lib/narrow.js';
 import { PushCommand } from '../lib/push-command.js';
+import {} from '../types/config.js';
 import { readLocalConfig } from '../utils/loopress-config.js';
 import { resolveResourceDir, RESOURCE_DIR_DEFAULTS } from '../utils/resource-dirs.js';
 export default class Promote extends Command {
@@ -18,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);
@@ -50,16 +54,16 @@ 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>.
                 // "untouched" is only true of <to>: a real (non dry-run) pull has already rewritten the files.
                 const filesNote = dryRun ? '' : ` Your local files may already hold part of ${from.name}, review them before pushing.`;
-                this.error(`Pull from ${from.name} failed, nothing was pushed to ${to.name}.${filesNote} ${error.message}`);
+                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) {
@@ -78,7 +82,10 @@ export default class Promote extends Command {
     // resource dir would land outside the copy, in the user's real files, during a dry run.
     async assertDirsInsideProject(projectDir) {
         const localConfig = await readLocalConfig();
-        const dirs = [localConfig.rootDir ?? '.', ...Object.keys(RESOURCE_DIR_DEFAULTS).map((kind) => resolveResourceDir(kind, localConfig))];
+        // Object.keys() is typed string[] even on an `as const` object: these are its own keys.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- see above
+        const kinds = Object.keys(RESOURCE_DIR_DEFAULTS);
+        const dirs = [localConfig.rootDir ?? '.', ...kinds.map((kind) => resolveResourceDir(kind, localConfig))];
         const outside = dirs.find((dir) => {
             const rel = relative(projectDir, resolve(projectDir, dir));
             return rel.startsWith('..') || isAbsolute(rel);
@@ -109,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,12 +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,6 +1,8 @@
 import { LoopressCommand } from '../lib/base.js';
+import { integrationFix, missingIntegration, missingModule } from '../lib/capabilities.js';
+import { declaredPlugins } from '../lib/declared-plugins.js';
 import { stdoutToStderr } from '../lib/json-delegation.js';
-import { INTEGRATION_MISSING } from '../lib/plugin-detection.js';
+import { errorMessage } from '../lib/narrow.js';
 import { pluralize } from '../utils/pluralize.js';
 import { projectUses, resolveResourceDir } from '../utils/resource-dirs.js';
 import { globalStylesSkipNote } from '../utils/theme-styles-format.js';
@@ -15,10 +17,11 @@ const PULL_TARGETS = [
     { commandId: 'meta:pull', label: 'post meta', supportsYes: true },
     { commandId: 'role:pull', label: 'roles', supportsYes: true },
     { commandId: 'acf:pull', label: 'ACF', needsPlugin: 'acf', supportsYes: true },
-    { commandId: 'api:pull', label: 'API routes', supportsYes: true },
-    { commandId: 'hook:pull', label: 'hooks', supportsYes: true },
+    { commandId: 'api:pull', label: 'API routes', needsPlugin: 'api', supportsYes: true },
+    { commandId: 'hook:pull', label: 'hooks', needsPlugin: 'hooks', supportsYes: true },
+    { commandId: 'block:pull', label: 'dynamic blocks', needsPlugin: 'block', supportsYes: true },
     { commandId: 'form:pull', label: 'forms', needsPlugin: 'form', supportsYes: true },
-    { commandId: 'pattern:pull', label: 'patterns', supportsYes: true },
+    { commandId: 'pattern:pull', label: 'patterns', needsPlugin: 'pattern', supportsYes: true },
     // Templates and parts have no pull. Global Styles are pulled only once the project tracks them,
     // see globalStylesSkipNote.
     { commandId: 'theme:style:pull', label: 'Global Styles' },
@@ -26,18 +29,31 @@ const PULL_TARGETS = [
     { commandId: 'option:pull', label: 'options', supportsYes: true },
     { commandId: 'snippet:pull', label: 'snippets', needsPlugin: 'snippets', supportsYes: true },
 ];
+// Why this site can't give the target. Composer has no directory to tell whether the project
+// uses it: never pulled from Light, which has nothing to give.
+function missingFor(target, capabilities) {
+    if (target.commandId === 'composer:pull')
+        return missingModule('dependencies', 'Composer files', capabilities);
+    return target.needsPlugin === undefined ? undefined : missingIntegration(target.needsPlugin, capabilities);
+}
 export default class Pull extends LoopressCommand {
-    static description = 'Pull every tracked resource from WordPress into local files in one run: composer dependencies, plugins, post types, taxonomies, post meta, roles, ACF, API routes, hooks, forms, patterns, Global Styles, menus, options, and snippets';
+    static description = 'Pull every tracked resource from WordPress into local files in one run: composer dependencies, plugins, post types, taxonomies, post meta, roles, ACF, API routes, hooks, dynamic blocks, forms, patterns, Global Styles, menus, options, and snippets';
     static enableJsonFlag = true;
     static examples = ['$ lps pull', '$ lps pull --env staging', '$ lps pull --dry-run'];
     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 = [];
-        this.warnRemovedSeoModule();
+        const capabilities = await this.capabilities();
         for (const target of PULL_TARGETS) {
             const skipNote = target.commandId === 'theme:style:pull' ? await this.globalStylesSkipNote() : undefined;
             if (skipNote) {
@@ -45,6 +61,11 @@ export default class Pull extends LoopressCommand {
                 results.push({ label: target.label, status: 'skipped' });
                 continue;
             }
+            const unavailable = this.unavailable(target, capabilities);
+            if (unavailable) {
+                results.push(unavailable);
+                continue;
+            }
             this.log(`\n→ Pulling ${target.label}...`);
             try {
                 await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand(target.commandId, this.buildArgv(target)));
@@ -52,30 +73,21 @@ export default class Pull extends LoopressCommand {
                 results.push({ label: target.label, status: 'pulled' });
             }
             catch (error) {
-                const { message } = error;
-                // A site without ACF (or a form or snippet plugin) is the common case, not a failure,
-                // as long as the project doesn't use that resource: a vanilla site must pull, and a
-                // promote must not stop on it. A project that does use it still fails.
-                if (target.needsPlugin && INTEGRATION_MISSING.test(message) && !projectUses(target.needsPlugin, this.localConfig)) {
-                    // oclif's catch already set exitCode to 1 for the sub-command; a real failure still
-                    // exits non-zero through the this.error() below.
-                    process.exitCode = undefined;
-                    this.log(`→ ${target.label}: not configured, skipped`);
-                    results.push({ label: target.label, status: 'skipped' });
-                    continue;
-                }
+                const message = errorMessage(error);
                 this.failedCount++;
                 this.log(`✗ ${target.label} failed: ${message}`);
                 results.push({ error: message, label: target.label, status: 'failed' });
             }
         }
         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
@@ -97,4 +109,41 @@ export default class Pull extends LoopressCommand {
             return undefined;
         }
     }
+    // Composer has no directory: counted as unused, see missingFor.
+    projectUses(target) {
+        return target.needsPlugin !== undefined && projectUses(target.needsPlugin, this.localConfig);
+    }
+    // A site without ACF (or a form or snippet plugin) is the common case, not a failure, as
+    // long as the project doesn't use that resource: a vanilla site must pull, and a promote
+    // must not stop on it. A project that does use it still fails, without asking the site.
+    // Same for a Loopress Full feature on Light.
+    unavailable(target, capabilities) {
+        const missing = missingFor(target, capabilities);
+        if (!missing)
+            return undefined;
+        if (!this.projectUses(target)) {
+            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,15 +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 composerDeclaresPlugins;
     private composerJsonPath;
+    private declaredPlugins;
+    private doneMessage;
     private globalStylesSkipNote;
     private guardProductionPush;
     private skippedTargets;
+    private unsupportedLine;
+    private warnUnsupported;
 }
 export {};

package/dist/commands/push.js

@@ -2,63 +2,84 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { LoopressCommand } from '../lib/base.js';
+import { integrationFix, missingIntegration, missingModule } from '../lib/capabilities.js';
 import { guardProductionPush } from '../lib/guard-production-push.js';
 import { stdoutToStderr } from '../lib/json-delegation.js';
+import { errorMessage } from '../lib/narrow.js';
 import { PushCommand } from '../lib/push-command.js';
+import { parseSelectionFlag, selectionFlags, selectResources } from '../lib/resource-selection.js';
 import { isLocalEnvironment } from '../lib/wp-client.js';
-import { wpackagistRequire } from '../utils/composer.js';
-import { projectUses, resolveResourceDir } from '../utils/resource-dirs.js';
+import { pinActive } from '../types/plugin.js';
+import { parseComposerJson, wpackagistRequire } from '../utils/composer.js';
+import { projectHasChildThemeFiles, projectUses, resolveResourceDir } from '../utils/resource-dirs.js';
 import { globalStylesSkipNote } from '../utils/theme-styles-format.js';
 // Backed by a plugin the site may not have (ACF, a form or a snippet plugin): a project without
 // the resource's directory doesn't use it, and its push, dry run included, would only stop on the
 // site's 409 or the missing directory.
 const PLUGIN_BACKED = { 'acf:push': 'acf', 'form:push': 'form', 'snippet:push': 'snippets' };
+// Features of Loopress Full only: on Light, skipped while the project doesn't use them, refused
+// upfront when it does. Like every other resource, skipped when the project doesn't use them.
+const FULL_ONLY = { 'api:push': 'api', 'block:push': 'block', 'hook:push': 'hooks', 'page:push': 'page', 'pattern:push': 'pattern' };
+// Always available on the site: nothing to refuse, but a project without the resource's
+// directory has nothing to push, so the step is skipped instead of running on an empty directory.
+const CORE_BACKED = { 'cpt:push': 'cpt', 'menu:push': 'menu', 'meta:push': 'meta', 'option:push': 'options', 'role:push': 'role', 'taxonomy:push': 'taxonomy' };
 // Dependency-ish order: code first (plugins, composer), then the ACF definitions content
 // relies on, then content itself.
 const PUSH_TARGETS = [
-    { commandId: 'plugin:push', label: 'plugins' },
-    { commandId: 'composer:push', label: 'composer' },
+    { commandId: 'plugin:push', id: 'plugin', label: 'plugins' },
+    { commandId: 'composer:push', id: 'composer', label: 'composer' },
     // Before ACF: a field group's location rule can target a Loopress post type or taxonomy.
-    { commandId: 'cpt:push', label: 'post types' },
-    { commandId: 'taxonomy:push', label: 'taxonomies' },
-    { commandId: 'meta:push', label: 'post meta' },
-    { commandId: 'role:push', label: 'roles' },
-    { commandId: 'acf:push', label: 'ACF' },
-    { commandId: 'api:push', label: 'API routes' },
-    { commandId: 'hook:push', label: 'hooks' },
-    { commandId: 'form:push', label: 'forms' },
+    { commandId: 'cpt:push', id: 'cpt', label: 'post types' },
+    { commandId: 'taxonomy:push', id: 'taxonomy', label: 'taxonomies' },
+    { commandId: 'meta:push', id: 'meta', label: 'post meta' },
+    { commandId: 'role:push', id: 'role', label: 'roles' },
+    { commandId: 'acf:push', id: 'acf', label: 'ACF' },
+    { commandId: 'api:push', id: 'api', label: 'API routes' },
+    { commandId: 'hook:push', id: 'hook', label: 'hooks' },
+    // Before templates and pages, which place them (`wp:loopress/<slug>`).
+    { commandId: 'block:push', id: 'block', label: 'dynamic blocks' },
+    { commandId: 'form:push', id: 'form', label: 'forms' },
     // Before templates and pages, which can reference them (`wp:pattern`).
-    { commandId: 'pattern:push', label: 'patterns' },
+    { commandId: 'pattern:push', id: 'pattern', label: 'patterns' },
     // Before pages: WordPress refuses a page whose `template` it doesn't know yet.
-    { commandId: 'theme:template:push', label: 'templates and parts' },
+    { commandId: 'theme:template:push', id: 'template', label: 'templates and parts' },
     // Belong to whichever theme is active, so right after its templates. Theme versions stay out:
     // installing or removing themes is `lps theme push`'s call.
-    { commandId: 'theme:style:push', label: 'Global Styles' },
-    { commandId: 'page:push', label: 'pages' },
-    { commandId: 'menu:push', label: 'menus' },
-    { commandId: 'option:push', label: 'options' },
-    { commandId: 'snippet:push', label: 'snippets' },
+    { commandId: 'theme:style:push', id: 'theme-style', label: 'Global Styles' },
+    { commandId: 'page:push', id: 'page', label: 'pages' },
+    { commandId: 'menu:push', id: 'menu', label: 'menus' },
+    { commandId: 'option:push', id: 'option', label: 'options' },
+    { commandId: 'snippet:push', id: 'snippet', label: 'snippets' },
 ];
+const PUSH_IDS = PUSH_TARGETS.map((target) => target.id);
 export default class Push extends LoopressCommand {
-    static description = 'Push every local resource to WordPress in one run: plugins, composer dependencies, post types, taxonomies, post meta, roles, ACF, API routes, hooks, forms, patterns, templates and parts, Global Styles, pages, menus, options, and snippets';
+    static description = 'Push every local resource to WordPress in one run: plugins, composer dependencies, post types, taxonomies, post meta, roles, ACF, API routes, hooks, dynamic blocks, forms, patterns, templates and parts, Global Styles, pages, menus, options, and snippets';
     static enableJsonFlag = true;
-    static examples = ['$ lps push', '$ lps push --env staging', '$ lps push --dry-run'];
+    static examples = ['$ lps push', '$ lps push --env staging', '$ lps push --dry-run', '$ lps push --only acf,page', '$ lps push --skip plugin --skip composer'];
     static flags = {
         ...LoopressCommand.dryRunFlag,
         ...LoopressCommand.yesFlag,
+        ...selectionFlags('push', PUSH_IDS),
+        ...LoopressCommand.skipUnsupportedFlag,
         overwrite: PushCommand.baseFlags.overwrite,
     };
+    skipUnsupported = false;
+    // What --skip-unsupported held back, for the final warning.
+    unsupported = [];
     async run() {
         await this.guardProductionPush();
-        this.warnRemovedSeoModule();
+        const { flags } = await this.parse(Push);
+        this.skipUnsupported = flags['skip-unsupported'];
+        const skipFlag = parseSelectionFlag(flags.skip, 'skip', PUSH_IDS, (message) => this.error(message));
+        const selected = new Set(selectResources(PUSH_IDS, parseSelectionFlag(flags.only, 'only', PUSH_IDS, (message) => this.error(message)), skipFlag));
         const argv = this.buildArgv();
         const results = [];
-        const skips = await this.skippedTargets();
+        const skips = await this.skippedTargets(selected, skipFlag.includes('composer'));
         for (const target of PUSH_TARGETS) {
             const skip = skips.get(target.commandId);
             if (skip) {
                 this.log(`\n→ ${target.label}: ${skip.note}`);
-                results.push({ label: target.label, status: skip.status });
+                results.push({ label: target.label, ...(skip.reason && { reason: skip.reason }), status: skip.status });
                 continue;
             }
             this.log(`\n→ Pushing ${target.label}...`);
@@ -68,19 +89,48 @@ export default class Push extends LoopressCommand {
                 results.push({ label: target.label, result, status: 'pushed' });
             }
             catch (error) {
-                const { message } = error;
+                const message = errorMessage(error);
                 this.log(`✗ ${target.label} failed: ${message}`);
                 results.push({ error: message, label: target.label, status: 'failed' });
                 // Stop here: later targets depend on earlier ones (hooks use what composer installs,
                 // pages need their templates), so pushing them anyway can ship a silently broken site.
-                const skipped = PUSH_TARGETS.slice(PUSH_TARGETS.indexOf(target) + 1).map((next) => next.label);
+                const skipped = PUSH_TARGETS.slice(PUSH_TARGETS.indexOf(target) + 1)
+                    .filter((next) => !skips.has(next.commandId))
+                    .map((next) => next.label);
                 const skippedNote = skipped.length > 0 ? ` Not attempted: ${skipped.join(', ')}.` : '';
+                this.warnUnsupported();
                 this.error(`${target.label} failed to push: ${message}.${skippedNote}`);
             }
         }
-        this.log(this.dryRun ? '\nEvery resource would push.' : '\nAll resources pushed.');
+        this.log(this.doneMessage(selected.size < PUSH_IDS.length));
+        this.warnUnsupported();
         return { results };
     }
+    // A step the project uses on a site that can't hold it would only fail at its turn, after
+    // everything before it was pushed: refuse the whole run upfront, saying how to fix it. An unused
+    // one is skipped, saying why when the site lacks it.
+    applySiteSteps(steps, skips, declared) {
+        const blockers = [];
+        for (const { commandId, missing, skipUnused, used } of steps) {
+            if (used && missing) {
+                const line = this.unsupportedLine(commandId, missing, declared);
+                if (this.skipUnsupported) {
+                    skips.set(commandId, { note: `${missing.reason}, skipped (--skip-unsupported)`, reason: `${missing.reason} on ${this.siteConfig.name}`, status: 'skipped' });
+                    this.unsupported.push(line);
+                }
+                else
+                    blockers.push(line);
+            }
+            else if (!used && missing?.needsFull) {
+                skips.set(commandId, { note: `${missing.reason}, skipped`, status: 'skipped' });
+            }
+            else if (!used && skipUnused) {
+                skips.set(commandId, { note: 'not configured, skipped', status: 'skipped' });
+            }
+        }
+        if (blockers.length > 0)
+            this.error(`Nothing was pushed, the project uses what this site can't hold:\n  ${blockers.join('\n  ')}`);
+    }
     // Every delegated push always gets --yes: either this command's own guard already confirmed
     // production once above, or the target isn't production and there's nothing to confirm.
     // Without this, each delegated command would re-run its own production guard.
@@ -93,23 +143,28 @@ export default class Push extends LoopressCommand {
             argv.push('--overwrite');
         return argv;
     }
-    // A composer.json that declares plugins is pushed whole by `plugin:push` (with its activation
-    // safety), so `composer:push` would only run Composer on the server a second time.
-    async composerDeclaresPlugins() {
-        const path = this.composerJsonPath();
-        if (!existsSync(path))
-            return false;
+    composerJsonPath() {
+        return join(process.cwd(), this.rootDir, 'composer.json');
+    }
+    // The wordpress.org plugins the project declares: composer.json's wpackagist plugins when it
+    // exists, loopress.json's otherwise. Unreadable or invalid composer.json: none, the commands report it.
+    async declaredPlugins(hasComposerJson) {
+        if (!hasComposerJson)
+            return Object.keys(this.localConfig.plugins ?? {});
         try {
-            const composerJson = JSON.parse(await readFile(path, 'utf8'));
-            return Object.keys(wpackagistRequire(composerJson, 'plugin', isLocalEnvironment(this.siteConfig.name))).length > 0;
+            const composerJson = parseComposerJson(await readFile(this.composerJsonPath(), 'utf8'));
+            return Object.keys(wpackagistRequire(composerJson, 'plugin', isLocalEnvironment(this.siteConfig.name)));
         }
         catch {
-            // Unreadable: let both commands run and report the parse error themselves.
-            return false;
+            return [];
         }
     }
-    composerJsonPath() {
-        return join(process.cwd(), this.rootDir, 'composer.json');
+    // A run narrowed by --only / --skip must not read as a full push. Unused resources skipped
+    // on a plain run don't count: that run still pushes everything the project has.
+    doneMessage(narrowed) {
+        if (narrowed)
+            return this.dryRun ? '\nEvery selected resource would push, the others are skipped.' : '\nSelected resources pushed, the others are skipped.';
+        return this.dryRun ? '\nEvery resource would push.' : '\nAll resources pushed.';
     }
     // The site unreachable or the theme list refused: let the step run and report it itself.
     async globalStylesSkipNote() {
@@ -132,26 +187,80 @@ export default class Push extends LoopressCommand {
     }
     // Unconfigured is not a failure: a project that doesn't manage plugins or composer through
     // Loopress must not stop the run before anything else gets pushed.
-    async skippedTargets() {
+    // `composerSkipped`: `composer` was named in --skip, as opposed to just left out of --only.
+    async skippedTargets(selected, composerSkipped) {
         const skips = new Map();
+        const isSelected = (commandId) => selected.has(PUSH_TARGETS.find((target) => target.commandId === commandId)?.id ?? '');
         const notConfigured = { note: 'not configured, skipped', status: 'skipped' };
         const hasComposerJson = existsSync(this.composerJsonPath());
-        const composerPushedByPlugins = await this.composerDeclaresPlugins();
+        const declaredPlugins = await this.declaredPlugins(hasComposerJson);
+        // A composer.json that declares plugins is pushed whole by `plugin:push` (with its activation
+        // safety), so `composer:push` would only run Composer on the server a second time.
+        const composerPushedByPlugins = hasComposerJson && declaredPlugins.length > 0 && isSelected('plugin:push');
+        // That push runs Composer on the server, so a run told to skip Composer can't push plugins.
+        if (composerPushedByPlugins && composerSkipped) {
+            this.error('--skip composer conflicts with pushing plugins: composer.json declares them, so plugin push runs Composer on the server. Skip plugin too, or drop --skip composer.');
+        }
         if (composerPushedByPlugins)
             skips.set('composer:push', { note: 'already pushed whole by plugins', status: 'pushed' });
         else if (!hasComposerJson)
             skips.set('composer:push', notConfigured);
         // With a composer.json, plugins come from it only; otherwise from loopress.json.
-        const pluginsConfigured = hasComposerJson ? composerPushedByPlugins : Object.keys(this.localConfig.plugins ?? {}).length > 0;
-        if (!pluginsConfigured)
+        if (declaredPlugins.length === 0)
             skips.set('plugin:push', notConfigured);
-        for (const [commandId, kind] of Object.entries(PLUGIN_BACKED)) {
-            if (!projectUses(kind, this.localConfig))
-                skips.set(commandId, notConfigured);
-        }
-        const stylesNote = await this.globalStylesSkipNote();
+        const capabilities = await this.capabilities();
+        // Installed and activated by this run's first step, before the steps that need them: a fresh
+        // site (CI, a new staging) gets ACF from loopress.json and its field groups in one push.
+        // composer.json records no active state, so its plugins stay inactive until --activate.
+        const activatedByPush = hasComposerJson || !isSelected('plugin:push') ? [] : declaredPlugins.filter((slug) => pinActive(this.localConfig.plugins?.[slug]));
+        const missingDependencies = missingModule('dependencies', 'plugins and Composer', capabilities);
+        // A target left out by --only / --skip is reported skipped and never reaches the site checks,
+        // so it can't block the run.
+        const allSteps = [
+            ...['plugin:push', 'composer:push'].map((commandId) => ({ commandId, missing: missingDependencies, skipUnused: false, used: !skips.has(commandId) })),
+            ...Object.entries(PLUGIN_BACKED).map(([commandId, kind]) => {
+                const missing = missingIntegration(kind, capabilities);
+                // Not missing when one of the plugins that would provide it is activated earlier in the run.
+                const activated = missing?.plugins?.some((slug) => activatedByPush.includes(slug)) ?? false;
+                // A dry run activates nothing, so the site can't preview this step yet.
+                if (activated && this.dryRun)
+                    skips.set(commandId, { note: `${missing?.reason} until this push activates it, skipped`, status: 'skipped' });
+                return { commandId, missing: activated ? undefined : missing, skipUnused: true, used: projectUses(kind, this.localConfig) };
+            }),
+            ...Object.entries(FULL_ONLY).map(([commandId, kind]) => ({
+                commandId,
+                missing: missingIntegration(kind, capabilities),
+                skipUnused: true,
+                used: projectUses(kind, this.localConfig),
+            })),
+            ...Object.entries(CORE_BACKED).map(([commandId, kind]) => ({ commandId, missing: undefined, skipUnused: true, used: projectUses(kind, this.localConfig) })),
+            // Without templates, parts or CSS, the step would only write an empty child theme.
+            { commandId: 'theme:template:push', missing: missingIntegration('template', capabilities), skipUnused: true, used: projectHasChildThemeFiles(this.localConfig) },
+        ];
+        const steps = allSteps.filter((step) => isSelected(step.commandId));
+        this.applySiteSteps(steps, skips, { fromComposer: hasComposerJson, plugins: declaredPlugins });
+        const stylesNote = isSelected('theme:style:push') ? await this.globalStylesSkipNote() : undefined;
         if (stylesNote)
             skips.set('theme:style:push', { note: stylesNote, status: 'skipped' });
+        for (const target of PUSH_TARGETS) {
+            // Composer left out of --only still runs when plugin push syncs composer.json: say so.
+            if (composerPushedByPlugins && target.commandId === 'composer:push')
+                continue;
+            if (!selected.has(target.id))
+                skips.set(target.commandId, { note: 'not selected, skipped', status: 'skipped' });
+        }
         return skips;
     }
+    // "<resources>: <why> on <site>. <fix>", for the refusal and for the --skip-unsupported warning.
+    unsupportedLine(commandId, missing, declared) {
+        const label = PUSH_TARGETS.find((target) => target.commandId === commandId)?.label;
+        const fix = integrationFix(missing, declared);
+        const fixSentence = fix ? ` ${fix}.` : '';
+        return `${label}: ${missing.reason} on ${this.siteConfig.name}.${fixSentence}`;
+    }
+    warnUnsupported() {
+        if (this.unsupported.length > 0) {
+            this.warn(`Skipped with --skip-unsupported, this site can't hold them:\n  ${this.unsupported.join('\n  ')}\nResources that depend on them (a page placing a block, code calling a hook) may not work until they are pushed.`);
+        }
+    }
 }

package/dist/commands/snippet/publish.js

@@ -1,9 +1,11 @@
 import { Args, Command } from '@oclif/core';
-import { join } from 'node:path';
 import { ApiClient } from '../../lib/api-client.js';
 import { loadSnippets } from '../../lib/load-snippets.js';
+import { errorMessage } from '../../lib/narrow.js';
 import { resolveLinkedProject } from '../../lib/resolve-linked-project.js';
+import {} from '../../types/snippet.js';
 import { pluralize } from '../../utils/pluralize.js';
+import { resolveResourceDir } from '../../utils/resource-dirs.js';
 import { toSlug } from '../../utils/to-slug.js';
 // Publishes to the Loopress api (not a WordPress site), so this does not extend
 // `LoopressCommand`/`PushCommand`: those force an environment to be resolved, but a project
@@ -18,14 +20,16 @@ export default class Publish extends Command {
     async run() {
         const { args } = await this.parse(Publish);
         const { apiProjectId, localConfig, token } = await resolveLinkedProject((message) => this.error(message));
-        const path = args.path ?? join(localConfig.rootDir ?? '.', localConfig.snippetsDir ?? 'snippets');
+        const path = resolveResourceDir('snippets', localConfig, args.path);
         this.log(`Publishing snippets from ${path}`);
         let snippets;
         try {
-            snippets = await loadSnippets(path);
+            snippets = await loadSnippets(path, (message) => {
+                this.warn(message);
+            });
         }
         catch (error) {
-            this.error(error.message);
+            this.error(errorMessage(error));
         }
         const api = new ApiClient(token);
         try {
@@ -34,7 +38,7 @@ export default class Publish extends Command {
             });
         }
         catch (error) {
-            this.error(error.message);
+            this.error(errorMessage(error));
         }
         this.log(`Published ${pluralize(snippets.length, 'snippet')} to your Loopress account.`);
     }

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

@@ -1,6 +1,6 @@
 import { type PushChange, PushCommand } from '../../lib/push-command.js';
 type PushedSnippet = {
-    id?: number;
+    id?: number | undefined;
     name: string;
 };
 type PushResult = {