@loopress/cli 0.30.0 → 0.32.0

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 = {
@@ -28,7 +28,7 @@ export default class Push extends PushCommand {
         this.log(`Snippets path: ${path}`);
         const provider = getResourceStateProvider('snippet');
         const beforeState = await this.captureBeforePushState(provider, path);
-        const snippets = await this.loadSnippets(path);
+        const snippets = this.withoutDuplicateIds(await this.loadSnippets(path));
         this.log(`Found ${pluralize(snippets.length, 'snippet')} to push`);
         const pushed = [];
         await this.runPushTasks(snippets, (snippet) => snippet.name, async (snippet, task) => {
@@ -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' };
@@ -148,8 +148,11 @@ export default class Push extends PushCommand {
     toPayload(snippet) {
         return {
             active: snippet.active,
-            code: stripPhpOpeningTag(snippet.code),
-            description: `Imported from ${snippet.path}`,
+            // Only PHP files carry an editor-only `<?php` tag: an HTML snippet starting with an inline
+            // `<?php ... ?>` block is its real content and must reach WordPress untouched.
+            code: snippet.type === 'php' ? stripPhpOpeningTag(snippet.code) : snippet.code,
+            // The sidecar's description wins, so a pull then push never erases one written in wp-admin.
+            description: snippet.description ?? `Imported from ${snippet.path}`,
             insertMethod: snippet.insertMethod,
             location: snippet.location,
             name: snippet.name,
@@ -159,4 +162,22 @@ export default class Push extends PushCommand {
             type: snippet.type,
         };
     }
+    // Two files claiming the same id would each PUT over that id, the last one silently replacing
+    // the other on the site (seen after switching snippet provider, whose ids restart). Neither is
+    // pushed, and the push fails, until the files are fixed by hand.
+    withoutDuplicateIds(snippets) {
+        const pathsById = new Map();
+        for (const { id, path } of snippets) {
+            if (id !== undefined)
+                pathsById.set(id, [...(pathsById.get(id) ?? []), path]);
+        }
+        return snippets.filter((snippet) => {
+            const paths = snippet.id === undefined ? [] : pathsById.get(snippet.id);
+            if (paths.length < 2)
+                return true;
+            this.failedCount++;
+            this.warn(`Skipping "${snippet.path}": id ${snippet.id} is also used by ${paths.filter((p) => p !== snippet.path).join(', ')}.`);
+            return false;
+        });
+    }
 }

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/pull.js

@@ -16,8 +16,13 @@ export default class Pull extends LoopressCommand {
         const { url } = this.siteConfig;
         this.log(`Pulling themes from ${url}`);
         const raw = await this.wp.get('wp/v2/themes');
+        // A theme with no Version header can't be pinned, and `theme version push` would then fail on
+        // it: the Loopress child theme (`<parent>-loopress`, written by `theme template push`) is one.
         const installed = parseInstalledThemes(raw);
-        const incoming = Object.fromEntries(installed.map((t) => [t.slug, t.version]));
+        const unversioned = installed.filter((t) => t.version === '').map((t) => t.slug);
+        const incoming = Object.fromEntries(installed.filter((t) => t.version !== '').map((t) => [t.slug, t.version]));
+        if (unversioned.length > 0)
+            this.log(`  - Skipped: ${unversioned.join(', ')} (no version to pin)`);
         // A composer.json is authoritative over loopress.json: pin the live versions there instead.
         const composerJsonPath = join(process.cwd(), this.rootDir, 'composer.json');
         if (existsSync(composerJsonPath)) {

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/base.d.ts

@@ -14,6 +14,7 @@ export declare abstract class LoopressCommand extends Command {
     };
     protected dryRun: boolean;
     protected localConfig: LoopressLocalConfig;
+    protected overwrite: boolean;
     protected productionConfirmed: boolean;
     protected projectId: string;
     protected siteConfig: EnvironmentConfig;

package/dist/lib/base.js

@@ -28,6 +28,8 @@ export class LoopressCommand extends Command {
     };
     dryRun = false;
     localConfig = {};
+    // Set by PushCommand's --overwrite, see PushCommand.guardOutsideEdits.
+    overwrite = false;
     // Set by PushCommand's hidden --production-confirmed, see there.
     productionConfirmed = false;
     projectId;
@@ -58,6 +60,7 @@ export class LoopressCommand extends Command {
         }));
         this.dryRun = Boolean(flags['dry-run']);
         this.yes = Boolean(flags.yes);
+        this.overwrite = Boolean(flags.overwrite);
         this.productionConfirmed = Boolean(flags['production-confirmed']);
         this.localConfig = await readLocalConfig();
         const resolved = this.resolveEnvironment(flags.env);

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;
@@ -23,6 +24,7 @@ export type DiffTarget = {
 type DiffSides = {
     againstWp: undefined | WpClient;
     leftLabel: string;
+    rightHeading: string;
     rightLabel: string;
     warn: (message: string) => void;
 };
@@ -37,6 +39,7 @@ export declare abstract class DiffCommand extends LoopressCommand {
     abstract run(): Promise<DiffJson>;
     private computeResource;
     private out;
+    private renderFailure;
     private renderSection;
     private wpForEnvironment;
 }

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;
@@ -47,8 +48,16 @@ export class DiffCommand extends LoopressCommand {
     // a tally, and the verdict, then returns the structured result. Exit code: 1 on drift, 2
     // when a resource could not be compared (inconclusive), so the command doubles as a CI gate.
     async report(targets, sides) {
-        this.out(`Comparing ${c('bold', sides.leftLabel)} ${c('dim', '→')} ${c('bold', sides.rightLabel)}\n`);
+        this.out(`Comparing ${c('bold', sides.leftLabel)} ${c('dim', '→')} ${c('bold', sides.rightHeading)}\n`);
         const results = await Promise.all(targets.map(async (target) => this.computeResource(target, sides)));
+        // Every resource failing the same way (site down, bad credentials) is one problem: say it
+        // once instead of once per resource.
+        const sharedError = sharedFailure(results.map((result) => result.json.error));
+        if (sharedError !== undefined) {
+            // Named, since some resources may have compared fine (one that needs no request).
+            const failedTitles = results.filter((result) => result.json.error !== undefined).map((result) => result.title);
+            this.out(c('red', `error (${failedTitles.join(', ')}): ${sharedError}`));
+        }
         const resources = {};
         let drift = false;
         let failed = false;
@@ -56,12 +65,12 @@ 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;
-                const errorLabel = c('red', `error: ${result.json.error}`);
-                this.out(`${c('bold', result.title)}  ${errorLabel}`);
+                this.renderFailure(result.title, result.json.error, sharedError);
                 continue;
             }
             compared += 1;
@@ -73,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.'));
@@ -91,6 +103,7 @@ export class DiffCommand extends LoopressCommand {
         return {
             againstWp: against ? this.wpForEnvironment(against) : undefined,
             leftLabel: this.siteConfig.name,
+            rightHeading: against ?? 'local files',
             rightLabel: against ?? 'local',
             warn: (message) => {
                 this.warn(message);
@@ -113,13 +126,23 @@ 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) {
         if (!this.jsonEnabled())
             this.log(message);
     }
+    renderFailure(title, error, sharedError) {
+        // Already printed once by `report` when every failure is the same.
+        if (sharedError !== undefined)
+            return;
+        const errorLabel = c('red', `error: ${error}`);
+        this.out(`${c('bold', title)}  ${errorLabel}`);
+    }
     renderSection(title, stateDiff) {
         if (isEmptyDiff(stateDiff)) {
             this.out(`${c('bold', title)}  ${c('dim', 'in sync')}`);
@@ -180,3 +203,9 @@ function indentPatch(patch) {
         .join('\n')
         .trimEnd();
 }
+// The one error every failed resource shares, when more than one failed (see `report`).
+function sharedFailure(errors) {
+    const failures = errors.filter((error) => error !== undefined);
+    const distinct = new Set(failures);
+    return failures.length > 1 && distinct.size === 1 ? failures[0] : undefined;
+}

package/dist/lib/load-snippets.js

@@ -26,6 +26,7 @@ async function loadSnippet(path, file, onSkip) {
     }
     let id;
     let name;
+    let description;
     let type;
     let isActive = false;
     let tags = [];
@@ -40,6 +41,8 @@ async function loadSnippet(path, file, onSkip) {
         // `||`, not `??`: an empty-string name in the sidecar JSON counts as absent too.
         // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
         name = meta.name || undefined;
+        // Kept even when empty: a description cleared on purpose, not one to replace with "Imported from <path>".
+        description = meta.description;
         type = parseType(meta.type) ?? undefined;
         isActive = Boolean(meta.active);
         tags = Array.isArray(meta.tags) ? meta.tags.map(String) : [];
@@ -58,6 +61,7 @@ async function loadSnippet(path, file, onSkip) {
     return {
         active: isActive,
         code: content,
+        description,
         id,
         insertMethod: insertMethod ?? 'auto',
         location: location ?? defaultLocationForType(resolvedType),

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[];
@@ -30,8 +30,17 @@ type RemotePhpFile = {
     filename: string;
     public?: boolean;
     revision?: string;
+    runtimeError?: RuntimeError;
 };
+export type RuntimeError = {
+    at: string;
+    message: string;
+    method: string;
+    type: 'action' | 'cron' | 'filter';
+};
+export declare function formatRuntimeError(error: RuntimeError): string;
 type PushResult = {
+    changes?: PushChange[];
     pruned: string[];
     pushed: string[];
     status: 'dry-run' | 'success';
@@ -59,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';
@@ -14,11 +15,37 @@ import { loadFiles as loadDirectoryFiles } from './load-files.js';
 import { PushCommand } from './push-command.js';
 import { getResourceStateProvider } from './resource-state.js';
 import { isApplicative404 } from './wp-client.js';
+export function formatRuntimeError(error) {
+    return `${error.method}() threw while running as ${error.type === 'action' ? 'an' : 'a'} ${error.type}, last at ${error.at}: ${error.message}`;
+}
 // Mirrors wordpress-plugin FileWriter::DECLARE_PATTERN / withGuard(): the server rejects both
 // an absent declare(strict_types=1); and one that appears more than once (it needs a single
 // 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
@@ -91,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: [] }
@@ -177,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)
@@ -262,6 +280,8 @@ export function resourceListCommand(spec) {
             for (const file of files) {
                 const badges = [file.public ? '[PUBLIC]' : '', file.error ? `(${file.error})` : ''].filter(Boolean).join('  ');
                 this.log(badges ? `  ${file.filename}  ${badges}` : `  ${file.filename}`);
+                if (file.runtimeError)
+                    this.log(`    ${formatRuntimeError(file.runtimeError)}`);
             }
             if (files.some((file) => file.public)) {
                 this.log('');
@@ -348,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',
@@ -367,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/;