@loopress/cli 0.31.0 → 0.32.1

package/dist/commands/push.js

@@ -1,13 +1,18 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+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 { resolveResourceDir } from '../utils/resource-dirs.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 = [
@@ -26,13 +31,16 @@ 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 = {
@@ -55,9 +63,9 @@ export default class Push extends LoopressCommand {
             }
             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) {
                 const { message } = error;
@@ -103,6 +111,15 @@ export default class Push extends LoopressCommand {
     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() {
@@ -128,10 +145,13 @@ export default class Push extends LoopressCommand {
         const pluginsConfigured = hasComposerJson ? composerPushedByPlugins : Object.keys(this.localConfig.plugins ?? {}).length > 0;
         if (!pluginsConfigured)
             skips.set('plugin:push', notConfigured);
-        // The only push that fails on a missing directory (the others find 0 files), so a project
-        // that never used snippets would otherwise end every `lps push` on an ENOENT.
-        if (!existsSync(resolve(resolveResourceDir('snippets', this.localConfig))))
-            skips.set('snippet: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';
 };

package/dist/commands/snippet/push.js

@@ -13,7 +13,7 @@ export default class Push extends PushCommand {
     static args = {
         path: Args.string({ description: 'Path to snippets directory (overrides project config)' }),
     };
-    static description = 'Push snippets to WordPress. Local snippet files created or updated remotely are renamed on disk to the `<id>-<slug>` convention.';
+    static description = 'Push local snippet files to WordPress. Local snippet files created or updated remotely are renamed on disk to the `<id>-<slug>` convention.';
     static enableJsonFlag = true;
     static examples = ['$ lps snippet push', '$ lps snippet push ./snippets'];
     static flags = {
@@ -40,7 +40,7 @@ export default class Push extends PushCommand {
             this.error(`${pluralize(this.failedCount, 'snippet')} 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 snippets pushed.');
         return { pushed, status: 'success' };

package/dist/commands/theme/pull.js

@@ -7,7 +7,7 @@ const PULL_TARGETS = [
     { commandId: 'theme:style:pull', label: 'Global Styles' },
 ];
 export default class Pull extends LoopressCommand {
-    static description = 'Pull everything theme related from WordPress: theme versions and Global Styles';
+    static description = 'Pull everything theme related from WordPress: theme versions into loopress.json, then Global Styles into a local file';
     static enableJsonFlag = true;
     static examples = ['$ lps theme pull', '$ lps theme pull --env staging', '$ lps theme pull --dry-run'];
     static flags = {

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

@@ -2,6 +2,7 @@ import { LoopressCommand } from '../../lib/base.js';
 type PushTargetResult = {
     error?: string;
     label: string;
+    result?: unknown;
     status: 'failed' | 'pushed';
 };
 type PushResult = {

package/dist/commands/theme/push.js

@@ -13,7 +13,7 @@ const PUSH_TARGETS = [
     { commandId: 'theme:style:push', label: 'Global Styles' },
 ];
 export default class Push extends LoopressCommand {
-    static description = 'Push everything theme related to WordPress: theme versions, templates and parts, then Global Styles';
+    static description = 'Push everything theme related to WordPress: theme versions from loopress.json, then block templates and parts, then Global Styles. Never switches the active theme.';
     static enableJsonFlag = true;
     static examples = ['$ lps theme push', '$ lps theme push --env staging', '$ lps theme push --dry-run'];
     static flags = {
@@ -46,9 +46,9 @@ export default class Push extends LoopressCommand {
                 argv.push('--force');
             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(`✓ ${target.label} pushed`);
-                results.push({ label: target.label, status: 'pushed' });
+                results.push({ label: target.label, result, status: 'pushed' });
             }
             catch (error) {
                 const { message } = error;

package/dist/commands/theme/style/push.d.ts

@@ -1,5 +1,6 @@
-import { PushCommand } from '../../../lib/push-command.js';
+import { type PushChange, PushCommand } from '../../../lib/push-command.js';
 type ThemeStylePushResult = {
+    changes?: PushChange[];
     file: string;
     status: 'dry-run' | 'success';
 };

package/dist/commands/theme/style/push.js

@@ -32,12 +32,11 @@ export default class Push extends PushCommand {
             }
             throw error;
         }
-        if (this.dryRun) {
-            this.log(`[dry-run] Would push: ${file}`);
-            return { file, status: 'dry-run' };
-        }
+        // Only the active theme's file is pushed, whatever else the directory holds.
         const provider = getResourceStateProvider('theme-styles');
-        const beforeState = await this.captureBeforePushState(provider, dir);
+        const beforeState = await this.captureBeforePushState(provider, dir, (name) => name === stylesheet);
+        if (this.dryRun)
+            return { changes: this.previewChanges, file, status: 'dry-run' };
         const local = JSON.parse(raw);
         await this.wp.post(globalStylesEndpoint(id), { settings: local.settings ?? {}, styles: local.styles ?? {} });
         this.log(`Pushed: ${file}`);

package/dist/commands/theme/template/list.js

@@ -2,7 +2,7 @@ import { LoopressCommand } from '../../../lib/base.js';
 import { pluralize } from '../../../utils/pluralize.js';
 import { CHILD_THEME_ENDPOINT } from '../../../utils/template-format.js';
 export default class List extends LoopressCommand {
-    static description = 'Show the Loopress child theme of the active block theme: its templates, parts, and those edited in the Site Editor';
+    static description = 'Show the Loopress child theme of the active block theme: whether it is active, its templates and parts, and those edited in the Site Editor';
     static enableJsonFlag = true;
     static examples = ['$ lps theme template list'];
     async run() {

package/dist/commands/theme/template/push.d.ts

@@ -1,7 +1,16 @@
-import { PushCommand } from '../../../lib/push-command.js';
+import { type PushChange, PushCommand } from '../../../lib/push-command.js';
+type CssChange = {
+    id: string;
+    status: 'unknown' | PushChange['status'];
+};
 type PushResult = {
     active?: boolean;
     blockStyles: string[];
+    changes?: {
+        css: CssChange[];
+        parts: PushChange[];
+        templates: PushChange[];
+    };
     customized?: string[];
     parts: string[];
     status: 'dry-run' | 'success';
@@ -18,5 +27,6 @@ export default class Push extends PushCommand {
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<PushResult>;
+    private previewChildTheme;
 }
 export {};

package/dist/commands/theme/template/push.js

@@ -1,5 +1,5 @@
-import { PushCommand } from '../../../lib/push-command.js';
-import { getResourceStateProvider } from '../../../lib/resource-state.js';
+import { createHash } from 'node:crypto';
+import { logChanges, pushChanges, PushCommand } from '../../../lib/push-command.js';
 import { formatPageProblems } from '../../../utils/page-format.js';
 import { pluralize } from '../../../utils/pluralize.js';
 import { resolveResourceDir } from '../../../utils/resource-dirs.js';
@@ -33,9 +33,11 @@ export default class Push extends PushCommand {
         this.log(`Found ${pluralize(templates.length, 'template')}, ${pluralize(parts.length, 'part')}, ` +
             `${css.style ? 'a global stylesheet' : 'no global stylesheet'} and ${pluralize(css.blocks.length, 'block stylesheet')}`);
         if (this.dryRun) {
-            await this.previewRemote(getResourceStateProvider('template'), templatesPath);
-            this.log('[dry-run] Would rewrite the child theme with them.');
-            return { ...names, status: 'dry-run' };
+            const changes = await this.previewChildTheme(templates, parts, css);
+            logChanges((message) => { this.log(message); }, changes.templates, 'templates/');
+            logChanges((message) => { this.log(message); }, changes.parts, 'parts/');
+            logChanges((message) => { this.log(message); }, changes.css, 'css/');
+            return { ...names, changes, status: 'dry-run' };
         }
         const child = await this.wp.put(CHILD_THEME_ENDPOINT, { ...css, parts, templates });
         await this.recordSuccess();
@@ -62,4 +64,31 @@ export default class Push extends PushCommand {
             unknownBlocks,
         };
     }
+    // Same read and same refusal as previewRemote, one GET for templates, parts and CSS.
+    async previewChildTheme(templates, parts, css) {
+        let child;
+        try {
+            child = await this.wp.get(CHILD_THEME_ENDPOINT);
+        }
+        catch (error) {
+            this.error(`The site would refuse this push: ${error.message}`);
+        }
+        const localCss = new Map(css.blocks.map((block) => [`blocks/${block.name}.css`, sha256(block.css)]));
+        if (css.style !== '')
+            localCss.set('style.css', sha256(css.style));
+        const cssChanges = child.css
+            ? pushChanges(localCss, new Map(Object.entries(child.css)), { mirror: true })
+            : [...localCss.keys()].toSorted((a, b) => a.localeCompare(b)).map((id) => ({ id, status: 'unknown' }));
+        return {
+            css: cssChanges,
+            parts: pushChanges(bySlug(parts), bySlug(child.parts), { mirror: true }),
+            templates: pushChanges(bySlug(templates), bySlug(child.templates), { mirror: true }),
+        };
+    }
+}
+function bySlug(files) {
+    return new Map(files.map(({ slug, ...rest }) => [slug, rest]));
+}
+function sha256(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
 }

package/dist/commands/theme/version/push.js

@@ -9,7 +9,7 @@ import { lockedWpackagistSlugs } from '../../../utils/plugins.js';
 import { diffThemes, parseInstalledThemes } from '../../../utils/themes.js';
 const IN_SYNC = { installed: [], pinned: [], removed: [], status: 'in-sync' };
 export default class Push extends PushCommand {
-    static description = 'Install themes on WordPress to match loopress.json (versions only, never switches the active theme)';
+    static description = 'Install WordPress.org themes on WordPress to match loopress.json, via Composer + WPackagist (versions only, never switches the active theme)';
     static enableJsonFlag = true;
     static examples = ['$ lps theme version push', '$ lps theme version push --force'];
     static flags = {

package/dist/lib/declared-type-command.d.ts

@@ -1,8 +1,9 @@
 import { type DeclaredTypeSpec, type RegisteredItem } from '../utils/declared-type-format.js';
 import { LoopressCommand } from './base.js';
 import { type CommandClass } from './php-files-command.js';
-import { PushCommand } from './push-command.js';
+import { type PushChange, PushCommand } from './push-command.js';
 type PushResult = {
+    changes?: PushChange[];
     path: string;
     pushed: string[];
     status: 'dry-run' | 'success';

package/dist/lib/declared-type-command.js

@@ -54,7 +54,7 @@ export function declaredPushCommand(spec, description) {
                 this.error(`${pluralize(this.failedCount, spec.noun, spec.plural)} failed to push.`);
             }
             if (this.dryRun)
-                return { path, pushed, status: 'dry-run' };
+                return { changes: this.previewChanges, path, pushed, status: 'dry-run' };
             await this.recordSuccess();
             this.log(`All ${spec.plural} pushed.`);
             return { path, pushed, status: 'success' };

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

@@ -16,6 +16,7 @@ export type DiffJson = {
 };
 export type DiffTarget = {
     left: () => Promise<ResourceState>;
+    optional?: boolean;
     resource: string;
     right: () => Promise<ResourceState>;
     title: string;

package/dist/lib/diff-command.js

@@ -4,6 +4,7 @@ import { configManager } from '../config/project-config.manager.js';
 import { resolveResourceDir } from '../utils/resource-dirs.js';
 import { LoopressCommand } from './base.js';
 import { compareStates, isEmptyDiff } from './diff-state.js';
+import { INTEGRATION_MISSING } from './plugin-detection.js';
 import { composerLocalState, composerRemoteState, getResourceStateProvider } from './resource-state.js';
 import { WpClient } from './wp-client.js';
 const c = ux.colorize;
@@ -64,7 +65,8 @@ export class DiffCommand extends LoopressCommand {
         let added = 0;
         let removed = 0;
         let changed = 0;
-        for (const result of results) {
+        const checked = results.filter((result) => !result.skipped);
+        for (const result of checked) {
             resources[result.resource] = result.json;
             if (result.json.error !== undefined) {
                 failed = true;
@@ -80,6 +82,9 @@ export class DiffCommand extends LoopressCommand {
             if (result.drift)
                 drift = true;
         }
+        const skipped = results.filter((result) => result.skipped);
+        for (const result of skipped)
+            this.out(`${c('bold', result.title)}  ${c('dim', 'not configured, skipped')}`);
         this.out(`\n${compared} compared: ${changed} changed, ${added} added, ${removed} removed`);
         if (failed)
             this.out(c('red', 'Some resources could not be compared; this run is inconclusive.'));
@@ -121,7 +126,10 @@ export class DiffCommand extends LoopressCommand {
         }
         catch (error) {
             const { message } = error;
-            return { drift: false, json: { added: [], changed: [], error: message, removed: [] }, resource: target.resource, title: target.title };
+            const empty = { added: [], changed: [], removed: [] };
+            if (target.optional && INTEGRATION_MISSING.test(message))
+                return { drift: false, json: empty, resource: target.resource, skipped: true, title: target.title };
+            return { drift: false, json: { ...empty, error: message }, resource: target.resource, title: target.title };
         }
     }
     out(message) {

package/dist/lib/php-files-command.d.ts

@@ -2,7 +2,7 @@ import { type Config } from '@oclif/core';
 import { type EnvironmentConfig } from '../types/config.js';
 import { type ResourceDirKind } from '../utils/resource-dirs.js';
 import { LoopressCommand } from './base.js';
-import { PushCommand } from './push-command.js';
+import { type PushChange, PushCommand } from './push-command.js';
 export type PhpFilesResource = {
     afterPush?: (context: {
         filenames: string[];
@@ -40,6 +40,7 @@ export type RuntimeError = {
 };
 export declare function formatRuntimeError(error: RuntimeError): string;
 type PushResult = {
+    changes?: PushChange[];
     pruned: string[];
     pushed: string[];
     status: 'dry-run' | 'success';
@@ -67,6 +68,7 @@ export type ListFilesCommand = Omit<LoopressCommand, 'run'> & {
 export type RmFilesCommand = Omit<LoopressCommand, 'run'> & {
     run(): Promise<RmResult>;
 };
+export declare function phpFileProblems(spec: Pick<PhpFilesResource, 'filenamePattern' | 'invalidFilenameHint'>, filename: string, content: string): string[];
 export declare function resourcePushCommand(spec: PhpFilesResource): CommandClass<PushFilesCommand>;
 export declare function resourcePullCommand(spec: PhpFilesResource): CommandClass<PullFilesCommand>;
 export declare function resourceListCommand(spec: PhpFilesResource): CommandClass<ListFilesCommand>;

package/dist/lib/php-files-command.js

@@ -4,6 +4,7 @@ import { createHash } from 'node:crypto';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, sep } from 'node:path';
 import { authManager } from '../config/auth.manager.js';
+import { firstTopLevelSideEffect, startsWithStrictTypes } from '../utils/php-top-level.js';
 import { pluralize } from '../utils/pluralize.js';
 import { resolveResourceDir, RESOURCE_DIR_DEFAULTS } from '../utils/resource-dirs.js';
 import { ApiClient } from './api-client.js';
@@ -22,6 +23,29 @@ export function formatRuntimeError(error) {
 // unambiguous insertion point for the ABSPATH guard). Matching "exactly once" here, not just
 // presence, so a file that would still fail server-side doesn't falsely pass this check.
 const DECLARE_PATTERN = /declare\s*\(\s*strict_types\s*=\s*1\s*\)\s*;/g;
+// What push checks on a route or hook file before sending it (the server rejects the same):
+// shared with `lps validate`. The server still runs what needs WordPress (PHP syntax, class-name
+// collisions), so passing these doesn't guarantee the push.
+// `filename`: the path under the resource dir, without `.php`.
+export function phpFileProblems(spec, filename, content) {
+    const problems = [];
+    if (!spec.filenamePattern.test(filename))
+        problems.push(`Invalid filename "${filename}": ${spec.invalidFilenameHint}`);
+    const declareCount = content.match(DECLARE_PATTERN)?.length ?? 0;
+    if (declareCount !== 1) {
+        const reason = declareCount === 0 ? 'is missing' : 'appears more than once';
+        problems.push(`${filename}.php: "declare(strict_types=1);" ${reason}, it must appear exactly once as the first statement`);
+    }
+    else if (!startsWithStrictTypes(content)) {
+        problems.push(`${filename}.php: "declare(strict_types=1);" must be the first statement, right after <?php (one in a comment doesn't count)`);
+    }
+    const sideEffect = firstTopLevelSideEffect(content);
+    if (sideEffect !== null) {
+        problems.push(`${filename}.php: code outside the class (${sideEffect}) would run at load time, move it into the class. ` +
+            "Don't add an ABSPATH guard: the plugin adds one on push.");
+    }
+    return problems;
+}
 // A file's expected revision (#234), computed from `beforeState`: the remote listing already
 // read by `captureBeforePushState` right before this push, for the rollback snapshot. Its value
 // for a PHP file is exactly the file's own raw content string (see phpFilesProvider in
@@ -94,10 +118,8 @@ export function resourcePushCommand(spec) {
             // files without also landing the new ones.
             const pruneList = flags.prune ? await this.resolvePruneList(new Set(files.map((file) => file.filename))) : [];
             if (this.dryRun) {
-                for (const file of files)
-                    this.log(`[dry-run] Would push: ${file.filename}`);
                 await this.writeAfterPushSnapshot(provider, path, beforeState);
-                return { pruned: pruneList, pushed: files.map((file) => file.filename), status: 'dry-run' };
+                return { changes: this.previewChanges, pruned: pruneList, pushed: files.map((file) => file.filename), status: 'dry-run' };
             }
             const { pruned, pushed } = files.length === 0 && pruneList.length === 0
                 ? { pruned: [], pushed: [] }
@@ -180,14 +202,7 @@ export function resourcePushCommand(spec) {
             return orphans;
         }
         validateFileLocally(file, task) {
-            if (!spec.filenamePattern.test(file.filename)) {
-                const message = `Invalid filename "${file.filename}": ${spec.invalidFilenameHint}`;
-                this.reportTaskFailure(message, new Error(message), task);
-            }
-            const declareCount = file.content.match(DECLARE_PATTERN)?.length ?? 0;
-            if (declareCount !== 1) {
-                const reason = declareCount === 0 ? 'is missing' : 'appears more than once';
-                const message = `${file.filename}.php: "declare(strict_types=1);" ${reason}, it must appear exactly once as the first statement`;
+            for (const message of phpFileProblems(spec, file.filename, file.content)) {
                 this.reportTaskFailure(message, new Error(message), task);
             }
             if (task)
@@ -353,14 +368,14 @@ export const API_FILES_RESOURCE = {
     filenamePattern: /^(?!index$)(?:[a-z0-9-]+|\[[A-Za-z_]\w*\])(?:\/(?:[a-z0-9-]+|\[[A-Za-z_]\w*\]))*$/,
     invalidFilenameHint: 'each path segment must be lowercase letters, digits, and hyphens, or a bracketed dynamic segment like "[order_id]" (e.g. "invoice-pdf/[order_id].php"), and a root "index.php" is reserved: name the file, or nest it (orders/index.php is the /orders route)',
     label: 'API routes',
-    listDescription: 'List custom API route files from WordPress',
+    listDescription: 'List custom API route files currently on WordPress',
     noun: 'route file',
     orphanReason: 'whose route no longer exists on WordPress',
     pathLabel: 'API',
     pathNoun: 'api directory',
-    pullDescription: 'Pull custom API route files from WordPress',
-    pushDescription: 'Push custom API route files to WordPress',
-    rmDescription: 'Remove a custom API route file from WordPress',
+    pullDescription: 'Pull custom API route files from WordPress into local files',
+    pushDescription: 'Push local custom API route files to WordPress',
+    rmDescription: 'Remove one custom API route file from WordPress',
 };
 export const HOOK_FILES_RESOURCE = {
     cliName: 'hook',
@@ -372,12 +387,12 @@ export const HOOK_FILES_RESOURCE = {
     filenamePattern: /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/,
     invalidFilenameHint: 'each path segment must be lowercase letters, digits, and hyphens (e.g. "content-filters.php" or "content/filters.php")',
     label: 'hooks',
-    listDescription: 'List hook files (actions, filters, cron) from WordPress',
+    listDescription: 'List hook files (actions, filters, cron) currently on WordPress',
     noun: 'hook file',
     orphanReason: 'no longer present on WordPress',
     pathLabel: 'Hooks',
     pathNoun: 'hooks directory',
-    pullDescription: 'Pull hook files (actions, filters, cron) from WordPress',
-    pushDescription: 'Push hook files (actions, filters, cron) to WordPress',
-    rmDescription: 'Remove a hook file (action, filter, cron) from WordPress',
+    pullDescription: 'Pull hook files (actions, filters, cron) from WordPress into local files',
+    pushDescription: 'Push local hook files (actions, filters, cron) to WordPress',
+    rmDescription: 'Remove one hook file (action, filter, cron) from WordPress',
 };

package/dist/lib/plugin-detection.d.ts

@@ -6,3 +6,4 @@ import { type WpClient } from './wp-client.js';
  * see Loopress Full itself.
  */
 export declare function isLoopressFullActive(wp: WpClient): Promise<boolean>;
+export declare const INTEGRATION_MISSING: RegExp;

package/dist/lib/plugin-detection.js

@@ -9,3 +9,7 @@ export async function isLoopressFullActive(wp) {
     const plugins = await wp.get('wp/v2/plugins');
     return plugins.some((plugin) => plugin.plugin.startsWith(FULL_PLUGIN_PREFIX) && plugin.status === 'active');
 }
+// How the Loopress plugin reports a resource's integration missing: "ACF is not active", "No
+// supported form plugin is active", "No supported snippet plugin is active". Global Styles say a
+// classic theme is active. The aggregate commands skip such a resource the project doesn't use.
+export const INTEGRATION_MISSING = /\bis not active\b|\bNo supported .+ plugin is active\b|\bis a classic theme\b/;

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

@@ -1,6 +1,18 @@
 import { LoopressCommand } from './base.js';
 import { type ResourceState } from './diff-state.js';
 import { type ResourceStateProvider } from './resource-state.js';
+export type PushChange = {
+    id: string;
+    status: 'changed' | 'created' | 'removed' | 'unchanged';
+};
+export declare function pushChanges(local: ResourceState, remote: ResourceState, options?: {
+    mirror?: boolean;
+    writes?: (id: string) => boolean;
+}): PushChange[];
+export declare function logChanges(log: (message: string) => void, changes: Array<{
+    id: string;
+    status: string;
+}>, prefix?: string): void;
 export declare abstract class PushCommand extends LoopressCommand {
     static baseFlags: {
         overwrite: import("@oclif/core/interfaces").BooleanFlag<boolean>;
@@ -8,6 +20,11 @@ export declare abstract class PushCommand extends LoopressCommand {
         env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     protected failedCount: number;
+    protected previewChanges: PushChange[];
+    protected previewStates?: {
+        local: ResourceState;
+        remote: ResourceState;
+    };
     private refusedByGuard;
     protected captureBeforePushState(provider: ResourceStateProvider, dir: string, writes?: (id: string) => boolean): Promise<ResourceState | undefined>;
     catch(err: Error): Promise<void>;

package/dist/lib/push-command.js

@@ -11,15 +11,41 @@ import { guardProductionPush } from './guard-production-push.js';
 import { isInteractive } from './interactive.js';
 import { readSnapshot, recordToState, writeSnapshot } from './snapshot-store.js';
 import { withoutSpinner, withSpinner } from './spinner.js';
+export function pushChanges(local, remote, options = {}) {
+    const changes = [...local.keys()]
+        .filter((id) => options.writes?.(id) ?? true)
+        .map((id) => {
+        if (!remote.has(id))
+            return { id, status: 'created' };
+        return { id, status: isDeepStrictEqual(local.get(id), remote.get(id)) ? 'unchanged' : 'changed' };
+    });
+    if (options.mirror) {
+        for (const id of remote.keys())
+            if (!local.has(id))
+                changes.push({ id, status: 'removed' });
+    }
+    return changes.toSorted((a, b) => a.id.localeCompare(b.id));
+}
+export function logChanges(log, changes, prefix = '') {
+    for (const change of changes)
+        log(`[dry-run] ${change.status}: ${prefix}${change.id}`);
+}
 export class PushCommand extends LoopressCommand {
     // Passed by an aggregate command (`lps theme push`) that already confirmed production once,
     // so its steps skip that prompt while still asking their own confirmations (uninstalls).
     static baseFlags = {
         ...LoopressCommand.baseFlags,
-        overwrite: Flags.boolean({ description: 'Push even over changes made on the site outside Loopress since your last push' }),
+        overwrite: Flags.boolean({
+            description: 'Push even over changes made on the site outside Loopress since your last push. Pages: also take over a same-slug page Loopress did not create',
+        }),
         'production-confirmed': Flags.boolean({ hidden: true }),
     };
     failedCount = 0;
+    // A dry run's per-item preview, set by captureBeforePushState: what the push would create,
+    // change or leave as it is on the site.
+    previewChanges = [];
+    // Both sides those statuses were computed from, for a push that details a changed item.
+    previewStates;
     // Refusals of the production guard never reach the site, so they must not pollute the
     // deployment history with failure records.
     refusedByGuard = false;
@@ -29,13 +55,26 @@ export class PushCommand extends LoopressCommand {
     // interrupt the push flow" stance recordDeployment takes; `undefined` tells
     // `writeAfterPushSnapshot` there is no restore point to complete.
     //
-    // On a dry run, the same read is the preview's check against the site (see previewRemote).
+    // On a dry run, the same read is the preview's check against the site (see previewRemote), and
+    // the reference for its per-item statuses (`previewChanges`).
     //
     // `writes` narrows the outside-edit check to the ids this push actually writes, for a push that
     // skips some local items (`lps page push <slug>`, readonly options, `lps acf push --type`).
     async captureBeforePushState(provider, dir, writes) {
         if (this.dryRun) {
-            await this.guardOutsideEdits(provider, dir, await this.previewRemote(provider, dir), writes);
+            const remote = await this.previewRemote(provider, dir);
+            await this.guardOutsideEdits(provider, dir, remote, writes);
+            try {
+                const local = await provider.local(dir, () => { });
+                this.previewStates = { local, remote };
+                this.previewChanges = pushChanges(local, remote, { writes });
+            }
+            catch (error) {
+                // The push reports the unreadable files itself, but an empty `changes` must not read as
+                // "nothing changes".
+                this.warn(`Could not list what this push would change: ${error.message}`);
+            }
+            logChanges((message) => { this.log(message); }, this.previewChanges);
             return undefined;
         }
         let remote;