@loopress/cli 0.30.0 → 0.32.0

package/dist/commands/page/push.js

@@ -1,6 +1,9 @@
+import { confirm } from '@inquirer/prompts';
 import { Args } from '@oclif/core';
+import { isInteractive } from '../../lib/interactive.js';
 import { PushCommand } from '../../lib/push-command.js';
 import { getResourceStateProvider } from '../../lib/resource-state.js';
+import { isConflictCode } from '../../lib/wp-client.js';
 import { formatPageProblems, frontPageNote, PAGES_ENDPOINT, readLocalPages } from '../../utils/page-format.js';
 import { pluralize } from '../../utils/pluralize.js';
 import { resolveResourceDir } from '../../utils/resource-dirs.js';
@@ -8,13 +11,15 @@ export default class Push extends PushCommand {
     static args = {
         slug: Args.string({ description: 'Push only this page (its file name without .html). Pushes every page when omitted.' }),
     };
-    static description = 'Push static HTML pages (pages/<slug>.html) to WordPress. The `status` header (draft or publish, draft by default) is applied on every push.';
+    static description = 'Push local static HTML pages (pages/<slug>.html) to WordPress, or only one when a slug is given. The `status` header (draft or publish, draft by default) is applied on every push.';
     static enableJsonFlag = true;
-    static examples = ['$ lps page push', '$ lps page push legal-notice', '$ lps page push --dry-run'];
+    static examples = ['$ lps page push', '$ lps page push legal-notice', '$ lps page push --dry-run', '$ lps page push about --overwrite'];
     static flags = {
         ...PushCommand.dryRunFlag,
         ...PushCommand.yesFlag,
     };
+    // Pages the site refused because a same-slug page exists there that Loopress didn't create.
+    unmanaged = [];
     async run() {
         const { args } = await this.parse(Push);
         const path = resolveResourceDir('page', this.localConfig);
@@ -29,34 +34,62 @@ export default class Push extends PushCommand {
             this.error(`No page "${args.slug}" in ${path} (expected ${args.slug}.html).`);
         }
         this.log(`Found ${pluralize(selected.length, 'page')} to push`);
-        if (this.dryRun)
-            await this.previewRemote(getResourceStateProvider('page'), path);
+        const provider = getResourceStateProvider('page');
+        const beforeState = await this.captureBeforePushState(provider, path, args.slug === undefined ? undefined : (id) => id === args.slug);
         const pushed = [];
         await this.runPushTasks(selected, (page) => page.slug, async (page, task) => {
-            await this.pushPage(page, task);
-            pushed.push(page.slug);
+            if (await this.pushPage(page, task))
+                pushed.push(page.slug);
         });
+        await this.adoptUnmanaged(pushed);
+        await this.writeAfterPushSnapshot(provider, path, beforeState);
         if (this.failedCount > 0) {
             this.error(`${pluralize(this.failedCount, 'page')} failed to push.`);
         }
         if (this.dryRun)
-            return { pushed, status: 'dry-run' };
+            return { changes: this.previewChanges, pushed, status: 'dry-run' };
         await this.recordSuccess();
         this.log('All pages pushed.');
         return { pushed, status: 'success' };
     }
-    async pushPage(page, task) {
+    // One prompt for every page the first pass set aside, then a second pass that takes them over.
+    // Without a terminal to ask in, they count as failed: CI must opt in with --overwrite.
+    async adoptUnmanaged(pushed) {
+        if (this.unmanaged.length === 0)
+            return;
+        const slugs = this.unmanaged.map((page) => page.slug);
+        this.warn(`Already on ${this.siteConfig.url} but not created by Loopress: ${slugs.join(', ')}. ` +
+            'Taking them over keeps their URL and ID, and shows your file instead of their current content (saved as a WordPress revision first). ' +
+            'Pass --overwrite to take them over.');
+        if (!isInteractive() || !(await confirm({ default: false, message: `Take over ${pluralize(slugs.length, 'page')}?` }))) {
+            this.failedCount += slugs.length;
+            return;
+        }
+        await this.runPushTasks(this.unmanaged, (page) => page.slug, async (page, task) => {
+            if (await this.pushPage(page, task, true))
+                pushed.push(page.slug);
+        });
+    }
+    // Resolves false when the page was set aside for adoptUnmanaged instead of pushed.
+    async pushPage(page, task, adopt = this.overwrite) {
         if (this.dryRun) {
             if (task)
                 task.output = `[dry-run] Would push: ${page.slug} (${page.status})`;
-            return;
+            return true;
         }
         try {
-            const result = await this.wp.put(PAGES_ENDPOINT, page);
+            const result = await this.wp.put(PAGES_ENDPOINT, adopt ? { ...page, adopt } : page);
             if (task)
                 task.output = `Pushed: ${page.slug} (${result.status}) ${result.link}${frontPageNote(result)}`;
+            return true;
         }
         catch (error) {
+            if (!adopt && isConflictCode(error, 'loopress_page_not_managed')) {
+                this.unmanaged.push(page);
+                // skip(): Listr's own "skipped" mark, not the green check of a page that was pushed.
+                task?.skip?.(`${page.slug} already exists on the site, not created by Loopress`);
+                return false;
+            }
             this.reportTaskFailure(`Failed to push ${page.slug}: ${error.message}`, error, task);
         }
     }

package/dist/commands/pattern/push.js

@@ -1,4 +1,4 @@
 import { declaredPushCommand } from '../../lib/declared-type-command.js';
 import { PATTERN_SPEC } from '../../utils/declared-type-format.js';
 export default declaredPushCommand(PATTERN_SPEC, 'Push local block patterns (patterns/<slug>.html, block markup under a title/categories header) to WordPress, ' +
-    'registered as loopress/<slug>. Create or update only, never deletes a pattern (use `lps pattern rm`).');
+    'registered as loopress/<slug> and referenced with <!-- wp:pattern {"slug":"loopress/<slug>"} /-->. Create or update only, never deletes a pattern (use `lps pattern rm`).');

package/dist/commands/pattern/rm.js

@@ -1,3 +1,3 @@
 import { declaredRmCommand } from '../../lib/declared-type-command.js';
 import { PATTERN_SPEC } from '../../utils/declared-type-format.js';
-export default declaredRmCommand(PATTERN_SPEC, 'Stop registering a Loopress block pattern on WordPress. A wp:pattern reference to it renders nothing, copies already inserted in posts stay.', 'A wp:pattern reference to it renders nothing until it is pushed again, copies already inserted in posts stay.');
+export default declaredRmCommand(PATTERN_SPEC, 'Stop registering a Loopress block pattern on WordPress. A wp:pattern reference to it renders nothing until it is pushed again, copies already inserted in posts stay.', 'A wp:pattern reference to it renders nothing until it is pushed again, copies already inserted in posts stay.');

package/dist/commands/plugin/audit.js

@@ -6,7 +6,7 @@ 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 description = 'Check the plugins in loopress.json for known vulnerabilities (wpvulnerability.net) and health issues';
     static enableJsonFlag = true;
     static examples = ['$ lps plugin audit'];
     static flags = {};
@@ -28,7 +28,12 @@ export default class Audit extends LoopressCommand {
     }
     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 }));
+        // "latest" is the newest WordPress.org release, the one a push installs: audit that version.
+        // Unknown (WordPress.org unreachable), every advisory is reported, safer than none.
+        const version = pinned === 'latest' && typeof info?.version === 'string' ? info.version : pinned;
+        const advisories = vulns
+            .filter((v) => version === 'latest' || affects(version, v.range))
+            .map(({ range: _range, ...v }) => ({ ...v, slug }));
         const health = info ? describeHealth(slug, pinned, info) : [];
         return { advisories, health };
     }
@@ -72,8 +77,13 @@ export default class Audit extends LoopressCommand {
         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);
+        // exit() throws before oclif prints the --json result, which a CI reading it needs most here.
+        if (advisories.length > 0) {
+            if (this.jsonEnabled())
+                process.exitCode = 1;
+            else
+                this.exit(1);
+        }
         return { advisories, health, status: 'issues' };
     }
 }
@@ -86,34 +96,41 @@ 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;
+    const range = extractRange(raw);
     return {
         cve,
-        fixedIn: extractFixedIn(raw),
+        fixedIn: range.max?.op === 'lt' ? range.max.version : undefined,
+        range,
         score: cvss.score,
         severity: cvss.severity,
-        title: typeof raw.name === 'string' ? raw.name : 'Unnamed advisory',
+        title: typeof raw.name === 'string' ? decodeEntities(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;
+// wpvulnerability's `operator`: `max_version` with `max_operator` "lt" (fixed in that version),
+// "le" (affected up to it, no fix yet) or "eq" (that version only), and an optional lower bound `min_version` with
+// `min_operator` "gt" or "ge". No upper bound means every version from the lower one on.
+function extractRange(raw) {
+    const op = (raw.operator ?? {});
+    const bound = (version, operator) => typeof version === 'string' && version !== '' && typeof operator === 'string' ? { op: operator, version } : undefined;
+    return { max: bound(op.max_version, op.max_operator), min: bound(op.min_version, op.min_operator) };
+}
+// A bound we can't evaluate (odd version strings, unknown operator) counts as affected: a false
+// positive is safer than hiding an advisory.
+function affects(version, range) {
+    const within = (bound, ok) => {
+        if (!bound)
+            return true;
+        const order = compareVersions(version, bound.version);
+        return order === null || !Object.hasOwn(ok, bound.op) || ok[bound.op](order);
+    };
+    return (within(range.min, { ge: (o) => o >= 0, gt: (o) => o > 0 }) && within(range.max, { eq: (o) => o === 0, le: (o) => o <= 0, lt: (o) => o < 0 }));
 }
-// 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;
+// Advisory names come HTML-encoded ("WPForms &#8211; AI Form Builder").
+function decodeEntities(text) {
+    return text
+        .replaceAll(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+        .replaceAll('&quot;', '"')
+        .replaceAll('&amp;', '&');
 }
 function describeHealth(slug, pinned, info) {
     const notes = [];

package/dist/commands/plugin/push.js

@@ -20,7 +20,7 @@ const IN_SYNC = {
     status: 'in-sync',
 };
 export default class Push extends PushCommand {
-    static description = 'Install plugins on WordPress to match loopress.json (or composer.json), via Composer + WPackagist';
+    static description = 'Install WordPress.org plugins on WordPress to match loopress.json (active state included) or composer.json, via Composer + WPackagist';
     static enableJsonFlag = true;
     static examples = ['$ lps plugin push', '$ lps plugin push --dry-run', '$ lps plugin push --force --prune'];
     static flags = {

package/dist/commands/plugin/status.js

@@ -4,7 +4,7 @@ import { LoopressCommand } from '../../lib/base.js';
 import { isNotFoundError } from '../../lib/wp-client.js';
 import { diffPlugins, lockedWpackagistSlugs, parseInstalledPlugins } from '../../utils/plugins.js';
 export default class Status extends LoopressCommand {
-    static description = 'Compare the plugins on WordPress against loopress.json and report drift';
+    static description = 'Compare the plugins on WordPress against loopress.json and report drift (missing, wrong version, inactive, untracked)';
     static enableJsonFlag = true;
     static examples = ['$ lps plugin status'];
     static flags = {};

package/dist/commands/promote.d.ts

@@ -13,6 +13,7 @@ export default class Promote extends Command {
     static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
+        overwrite: 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

@@ -8,6 +8,7 @@ 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 { PushCommand } from '../lib/push-command.js';
 import { readLocalConfig } from '../utils/loopress-config.js';
 import { resolveResourceDir, RESOURCE_DIR_DEFAULTS } from '../utils/resource-dirs.js';
 export default class Promote extends Command {
@@ -21,10 +22,11 @@ export default class Promote extends Command {
     static flags = {
         ...LoopressCommand.dryRunFlag,
         ...LoopressCommand.yesFlag,
+        overwrite: PushCommand.baseFlags.overwrite,
     };
     async run() {
         const { args, flags } = await this.parse(Promote);
-        const { yes } = flags;
+        const { overwrite, yes } = flags;
         const dryRun = flags['dry-run'];
         const { environments, projectName } = await this.resolveProject();
         const from = this.requireEnvironment(environments, projectName, args.from);
@@ -52,10 +54,12 @@ export default class Promote extends Command {
             }
             catch (error) {
                 // A partial pull must never be pushed onward: stop before touching <to>.
-                this.error(`Pull from ${from.name} failed, ${to.name} left untouched: ${error.message}`);
+                // "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.log(`\n=== Pushing to ${to.name} (${to.url}) ===`);
-            await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand('push', this.delegateArgv(to.name, dryRun)));
+            await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand('push', [...this.delegateArgv(to.name, dryRun), ...(overwrite ? ['--overwrite'] : [])]));
         }
         finally {
             if (scratch) {

package/dist/commands/pull.d.ts

@@ -2,7 +2,7 @@ import { LoopressCommand } from '../lib/base.js';
 type PullTargetResult = {
     error?: string;
     label: string;
-    status: 'failed' | 'pulled';
+    status: 'failed' | 'pulled' | 'skipped';
 };
 type PullResult = {
     results: PullTargetResult[];
@@ -18,5 +18,6 @@ export default class Pull extends LoopressCommand {
     private failedCount;
     run(): Promise<PullResult>;
     private buildArgv;
+    private globalStylesSkipNote;
 }
 export {};

package/dist/commands/pull.js

@@ -1,6 +1,9 @@
 import { LoopressCommand } from '../lib/base.js';
 import { stdoutToStderr } from '../lib/json-delegation.js';
+import { INTEGRATION_MISSING } from '../lib/plugin-detection.js';
 import { pluralize } from '../utils/pluralize.js';
+import { projectUses, resolveResourceDir } from '../utils/resource-dirs.js';
+import { globalStylesSkipNote } from '../utils/theme-styles-format.js';
 // composer before plugins: when a composer.json exists, `plugin:pull` merges the live plugins
 // into it, so it must run on the freshly pulled one or `composer:pull` would overwrite its work. The rest write to independent
 // directories and their order does not matter, it mirrors `lps push` for familiarity.
@@ -11,17 +14,20 @@ const PULL_TARGETS = [
     { commandId: 'taxonomy:pull', label: 'taxonomies', supportsYes: true },
     { commandId: 'meta:pull', label: 'post meta', supportsYes: true },
     { commandId: 'role:pull', label: 'roles', supportsYes: true },
-    { commandId: 'acf:pull', label: 'ACF', 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: 'form:pull', label: 'forms', supportsYes: true },
+    { commandId: 'form:pull', label: 'forms', needsPlugin: 'form', supportsYes: true },
     { commandId: 'pattern:pull', label: 'patterns', 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' },
     { commandId: 'menu:pull', label: 'menus', supportsYes: true },
     { commandId: 'option:pull', label: 'options', supportsYes: true },
-    { commandId: 'snippet:pull', label: 'snippets', supportsYes: true },
+    { commandId: 'snippet:pull', label: 'snippets', needsPlugin: 'snippets', supportsYes: true },
 ];
 export default class Pull extends LoopressCommand {
-    static description = 'Pull all content, plugins, composer dependencies, post types, taxonomies, post meta, roles, ACF, API routes, hooks, forms, patterns, menus, options, and snippets, from WordPress';
+    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 enableJsonFlag = true;
     static examples = ['$ lps pull', '$ lps pull --env staging', '$ lps pull --dry-run'];
     static flags = {
@@ -33,6 +39,12 @@ export default class Pull extends LoopressCommand {
         const results = [];
         this.warnRemovedSeoModule();
         for (const target of PULL_TARGETS) {
+            const skipNote = target.commandId === 'theme:style:pull' ? await this.globalStylesSkipNote() : undefined;
+            if (skipNote) {
+                this.log(`\n→ ${target.label}: ${skipNote}`);
+                results.push({ label: target.label, status: 'skipped' });
+                continue;
+            }
             this.log(`\n→ Pulling ${target.label}...`);
             try {
                 await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand(target.commandId, this.buildArgv(target)));
@@ -40,8 +52,19 @@ export default class Pull extends LoopressCommand {
                 results.push({ label: target.label, status: 'pulled' });
             }
             catch (error) {
-                this.failedCount++;
                 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;
+                }
+                this.failedCount++;
                 this.log(`✗ ${target.label} failed: ${message}`);
                 results.push({ error: message, label: target.label, status: 'failed' });
             }
@@ -65,4 +88,13 @@ export default class Pull extends LoopressCommand {
             argv.push('--yes');
         return argv;
     }
+    // The site unreachable or the theme list refused: let the step run and report it itself.
+    async globalStylesSkipNote() {
+        try {
+            return await globalStylesSkipNote(this.wp, resolveResourceDir('themeStyles', this.localConfig), 'pull');
+        }
+        catch {
+            return undefined;
+        }
+    }
 }

package/dist/commands/push.d.ts

@@ -2,7 +2,8 @@ import { LoopressCommand } from '../lib/base.js';
 type PushTargetResult = {
     error?: string;
     label: string;
-    status: 'failed' | 'pushed';
+    result?: unknown;
+    status: 'failed' | 'pushed' | 'skipped';
 };
 type PushResult = {
     results: PushTargetResult[];
@@ -12,13 +13,16 @@ export default class Push extends LoopressCommand {
     static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
+        overwrite: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
-    private failedCount;
     run(): Promise<PushResult>;
     private buildArgv;
     private composerDeclaresPlugins;
+    private composerJsonPath;
+    private globalStylesSkipNote;
     private guardProductionPush;
+    private skippedTargets;
 }
 export {};

package/dist/commands/push.js

@@ -4,9 +4,15 @@ import { join } from 'node:path';
 import { LoopressCommand } from '../lib/base.js';
 import { guardProductionPush } from '../lib/guard-production-push.js';
 import { stdoutToStderr } from '../lib/json-delegation.js';
+import { PushCommand } from '../lib/push-command.js';
 import { isLocalEnvironment } from '../lib/wp-client.js';
 import { wpackagistRequire } from '../utils/composer.js';
-import { pluralize } from '../utils/pluralize.js';
+import { 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' };
 // Dependency-ish order: code first (plugins, composer), then the ACF definitions content
 // relies on, then content itself.
 const PUSH_TARGETS = [
@@ -25,53 +31,53 @@ const PUSH_TARGETS = [
     { commandId: 'pattern:push', label: 'patterns' },
     // Before pages: WordPress refuses a page whose `template` it doesn't know yet.
     { commandId: 'theme:template:push', 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' },
 ];
 export default class Push extends LoopressCommand {
-    static description = 'Push all local content, plugins, composer dependencies, post types, taxonomies, post meta, roles, ACF, API routes, hooks, forms, patterns, templates, pages, menus, options, and snippets, to WordPress';
+    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 enableJsonFlag = true;
     static examples = ['$ lps push', '$ lps push --env staging', '$ lps push --dry-run'];
     static flags = {
         ...LoopressCommand.dryRunFlag,
         ...LoopressCommand.yesFlag,
+        overwrite: PushCommand.baseFlags.overwrite,
     };
-    failedCount = 0;
     async run() {
         await this.guardProductionPush();
         this.warnRemovedSeoModule();
         const argv = this.buildArgv();
         const results = [];
-        const composerPushedByPlugins = await this.composerDeclaresPlugins();
+        const skips = await this.skippedTargets();
         for (const target of PUSH_TARGETS) {
-            if (composerPushedByPlugins && target.commandId === 'composer:push') {
-                this.log('\n→ composer: already pushed whole by plugins');
-                results.push({ label: target.label, status: 'pushed' });
+            const skip = skips.get(target.commandId);
+            if (skip) {
+                this.log(`\n→ ${target.label}: ${skip.note}`);
+                results.push({ label: target.label, status: skip.status });
                 continue;
             }
             this.log(`\n→ Pushing ${target.label}...`);
             try {
-                await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand(target.commandId, argv));
+                const result = await stdoutToStderr(this.jsonEnabled(), async () => this.config.runCommand(target.commandId, argv));
                 this.log(this.dryRun ? `✓ ${target.label} would push` : `✓ ${target.label} pushed`);
-                results.push({ label: target.label, status: 'pushed' });
+                results.push({ label: target.label, result, status: 'pushed' });
             }
             catch (error) {
-                this.failedCount++;
                 const { message } = 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 skippedNote = skipped.length > 0 ? ` Not attempted: ${skipped.join(', ')}.` : '';
+                this.error(`${target.label} failed to push: ${message}.${skippedNote}`);
             }
         }
-        if (this.failedCount > 0) {
-            // 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 push. ${failures.join('; ')}`);
-        }
         this.log(this.dryRun ? '\nEvery resource would push.' : '\nAll resources pushed.');
         return { results };
     }
@@ -82,12 +88,15 @@ export default class Push extends LoopressCommand {
         const argv = ['--env', this.siteConfig.name, '--yes'];
         if (this.dryRun)
             argv.push('--dry-run');
+        // Not implied by --yes: overwriting changes made outside Loopress is its own decision.
+        if (this.overwrite)
+            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 = join(process.cwd(), this.rootDir, 'composer.json');
+        const path = this.composerJsonPath();
         if (!existsSync(path))
             return false;
         try {
@@ -99,6 +108,18 @@ export default class Push extends LoopressCommand {
             return false;
         }
     }
+    composerJsonPath() {
+        return join(process.cwd(), this.rootDir, 'composer.json');
+    }
+    // The site unreachable or the theme list refused: let the step run and report it itself.
+    async globalStylesSkipNote() {
+        try {
+            return await globalStylesSkipNote(this.wp, resolveResourceDir('themeStyles', this.localConfig), 'push');
+        }
+        catch {
+            return undefined;
+        }
+    }
     // Guards once here (shared with PushCommand, lib/push-command.ts) rather than once per
     // delegated command.
     async guardProductionPush() {
@@ -109,4 +130,28 @@ export default class Push extends LoopressCommand {
             yes: this.yes,
         });
     }
+    // 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() {
+        const skips = new Map();
+        const notConfigured = { note: 'not configured, skipped', status: 'skipped' };
+        const hasComposerJson = existsSync(this.composerJsonPath());
+        const composerPushedByPlugins = await this.composerDeclaresPlugins();
+        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)
+            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();
+        if (stylesNote)
+            skips.set('theme:style:push', { note: stylesNote, status: 'skipped' });
+        return skips;
+    }
 }

package/dist/commands/snippet/list.js

@@ -2,7 +2,7 @@ import { LoopressCommand } from '../../lib/base.js';
 import { pluralize } from '../../utils/pluralize.js';
 import { normalizeSnippet, SNIPPETS_ENDPOINT } from '../../utils/snippet-format.js';
 export default class List extends LoopressCommand {
-    static description = 'List snippets from WordPress';
+    static description = 'List snippets currently on WordPress';
     static enableJsonFlag = true;
     static examples = ['$ lps snippet list'];
     async run() {

package/dist/commands/snippet/pull.js

@@ -17,7 +17,7 @@ export default class Pull extends LoopressCommand {
     static args = {
         path: Args.string({ description: 'Path to snippets directory (overrides project config)' }),
     };
-    static description = 'Pull snippets from WordPress';
+    static description = 'Pull snippets from WordPress into local files';
     static enableJsonFlag = true;
     static examples = ['$ lps snippet pull', '$ lps snippet pull ./snippets'];
     static flags = {

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

@@ -1,9 +1,10 @@
-import { PushCommand } from '../../lib/push-command.js';
+import { type PushChange, PushCommand } from '../../lib/push-command.js';
 type PushedSnippet = {
     id?: number;
     name: string;
 };
 type PushResult = {
+    changes?: PushChange[];
     pushed: PushedSnippet[];
     status: 'dry-run' | 'success';
 };
@@ -24,5 +25,6 @@ export default class Push extends PushCommand {
     private loadSnippets;
     private pushSnippet;
     private toPayload;
+    private withoutDuplicateIds;
 }
 export {};