@loopress/cli 0.30.0 → 0.31.0

package/dist/commands/push.js

@@ -1,12 +1,13 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, resolve } 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 { resolveResourceDir } from '../utils/resource-dirs.js';
 // Dependency-ish order: code first (plugins, composer), then the ACF definitions content
 // relies on, then content itself.
 const PUSH_TARGETS = [
@@ -37,18 +38,19 @@ export default class Push extends LoopressCommand {
     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}...`);
@@ -58,20 +60,16 @@ export default class Push extends LoopressCommand {
                 results.push({ label: target.label, 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 +80,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 +100,9 @@ export default class Push extends LoopressCommand {
             return false;
         }
     }
+    composerJsonPath() {
+        return join(process.cwd(), this.rootDir, 'composer.json');
+    }
     // Guards once here (shared with PushCommand, lib/push-command.ts) rather than once per
     // delegated command.
     async guardProductionPush() {
@@ -109,4 +113,25 @@ 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);
+        // 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);
+        return skips;
+    }
 }

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

@@ -24,5 +24,6 @@ export default class Push extends PushCommand {
     private loadSnippets;
     private pushSnippet;
     private toPayload;
+    private withoutDuplicateIds;
 }
 export {};

package/dist/commands/snippet/push.js

@@ -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) => {
@@ -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/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/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/diff-command.d.ts

@@ -23,6 +23,7 @@ export type DiffTarget = {
 type DiffSides = {
     againstWp: undefined | WpClient;
     leftLabel: string;
+    rightHeading: string;
     rightLabel: string;
     warn: (message: string) => void;
 };
@@ -37,6 +38,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

@@ -47,8 +47,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;
@@ -60,8 +68,7 @@ export class DiffCommand extends LoopressCommand {
             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;
@@ -91,6 +98,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);
@@ -120,6 +128,13 @@ export class DiffCommand extends LoopressCommand {
         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 +195,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

@@ -30,7 +30,15 @@ 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 = {
     pruned: string[];
     pushed: string[];

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

@@ -14,6 +14,9 @@ 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
@@ -262,6 +265,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('');

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

@@ -3,16 +3,17 @@ import { type ResourceState } from './diff-state.js';
 import { type ResourceStateProvider } from './resource-state.js';
 export declare abstract class PushCommand extends LoopressCommand {
     static baseFlags: {
+        overwrite: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'production-confirmed': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     protected failedCount: number;
     private refusedByGuard;
-    protected captureBeforePushState(provider: ResourceStateProvider, dir: string): Promise<ResourceState | undefined>;
+    protected captureBeforePushState(provider: ResourceStateProvider, dir: string, writes?: (id: string) => boolean): Promise<ResourceState | undefined>;
     catch(err: Error): Promise<void>;
     protected guardProductionPush(): Promise<void>;
     init(): Promise<void>;
-    protected previewRemote(provider: ResourceStateProvider, dir: string): Promise<void>;
+    protected previewRemote(provider: ResourceStateProvider, dir: string): Promise<ResourceState>;
     protected recordDeployment(status: 'failure' | 'success'): Promise<void>;
     protected recordSuccess(): Promise<void>;
     protected reportPushToSite(): Promise<void>;
@@ -23,4 +24,5 @@ export declare abstract class PushCommand extends LoopressCommand {
         output: string;
     }) => Promise<void>): Promise<void>;
     protected writeAfterPushSnapshot(provider: ResourceStateProvider, dir: string, beforeState: ResourceState | undefined): Promise<void>;
+    private guardOutsideEdits;
 }

package/dist/lib/push-command.js

@@ -1,18 +1,22 @@
+import { confirm } from '@inquirer/prompts';
 import { Flags } from '@oclif/core';
 import got from 'got';
 import { Listr } from 'listr2';
 import { resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { authManager } from '../config/auth.manager.js';
 import { API_URL } from './api-client.js';
 import { LoopressCommand } from './base.js';
 import { guardProductionPush } from './guard-production-push.js';
-import { writeSnapshot } from './snapshot-store.js';
+import { isInteractive } from './interactive.js';
+import { readSnapshot, recordToState, writeSnapshot } from './snapshot-store.js';
 import { withoutSpinner, withSpinner } from './spinner.js';
 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' }),
         'production-confirmed': Flags.boolean({ hidden: true }),
     };
     failedCount = 0;
@@ -26,13 +30,17 @@ export class PushCommand extends LoopressCommand {
     // `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).
-    async captureBeforePushState(provider, dir) {
+    //
+    // `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.previewRemote(provider, dir);
+            await this.guardOutsideEdits(provider, dir, await this.previewRemote(provider, dir), writes);
             return undefined;
         }
+        let remote;
         try {
-            return await provider.remote(this.wp, (message) => {
+            remote = await provider.remote(this.wp, (message) => {
                 this.warn(message);
             }, dir);
         }
@@ -40,6 +48,8 @@ export class PushCommand extends LoopressCommand {
             this.warn(`Could not read remote state for a rollback snapshot: ${error.message}`);
             return undefined;
         }
+        await this.guardOutsideEdits(provider, dir, remote, writes);
+        return remote;
     }
     async catch(err) {
         if (!this.dryRun && !this.refusedByGuard && this.siteConfig) {
@@ -68,7 +78,7 @@ export class PushCommand extends LoopressCommand {
     // pre-apply check built on it, see what the real push will hit.
     async previewRemote(provider, dir) {
         try {
-            await provider.remote(this.wp, () => { }, dir);
+            return await provider.remote(this.wp, () => { }, dir);
         }
         catch (error) {
             this.error(`The site would refuse this push: ${error.message}`);
@@ -165,4 +175,54 @@ export class PushCommand extends LoopressCommand {
             this.warn(`Could not save a rollback snapshot after this push: ${error.message}`);
         }
     }
+    // Refuses to silently overwrite a change made on the site outside Loopress (wp-admin, another
+    // tool) since this machine's last push. Flags an id only when both hold:
+    // - the site no longer matches what that push left (the latest snapshot's `afterState`, the
+    //   same reference rollback's drift check uses), and
+    // - this push would write a different value over it (local differs from the site), so a
+    //   `pull` that already brought the change into the local files is no reason to stop.
+    // Only ids present locally count: a push is additive, it never touches a site-only id. And
+    // only ids the site still has with readable content: pushing over a deletion (`lps <resource>
+    // rm`, or wp-admin) loses nothing, and a file the site lists without its content (too large
+    // to send) can't be compared, so it would otherwise block every push.
+    // Ceiling: snapshots live in git-ignored `.loopress/`, so only the machine that pushed last
+    // is protected; a record kept on the site would cover teammates and CI.
+    async guardOutsideEdits(provider, dir, remote, writes) {
+        if (this.overwrite)
+            return;
+        let expected;
+        let local;
+        let pushedAt;
+        try {
+            const snapshot = await readSnapshot(resolve(process.cwd(), this.rootDir), provider.resource, this.siteConfig.name);
+            expected = recordToState(snapshot.afterState);
+            pushedAt = snapshot.createdAt;
+            local = await provider.local(dir, () => { });
+        }
+        catch {
+            // No earlier push from this machine, or unreadable local files the push reports itself.
+            return;
+        }
+        const overwritten = [...local.keys()].filter((id) => (writes?.(id) ?? true) &&
+            remote.get(id) !== undefined &&
+            !sameEntry(remote, expected, id) &&
+            !sameEntry(local, remote, id));
+        if (overwritten.length === 0)
+            return;
+        const message = `Changed on ${this.siteConfig.url} outside Loopress since your last push (${pushedAt}), this push would overwrite: ${overwritten.join(', ')}. ` +
+            `Review with \`lps diff --only ${provider.resource}\`, bring the site's version into your files, or pass --overwrite.`;
+        // A dry run only previews: say what the real push would stop on.
+        if (this.dryRun) {
+            this.warn(message);
+            return;
+        }
+        if (!isInteractive())
+            this.error(message);
+        this.warn(message);
+        if (!(await confirm({ default: false, message: 'Overwrite those changes?' })))
+            this.error('Aborted.');
+    }
+}
+function sameEntry(left, right, id) {
+    return left.has(id) === right.has(id) && isDeepStrictEqual(left.get(id), right.get(id));
 }

package/dist/lib/resource-state.js

@@ -31,14 +31,14 @@ const ACF_VOLATILE_KEYS = ['modified'];
 // A WPForms form is a WP post; `modified`/`modified_gmt` move on every edit.
 const FORM_VOLATILE_KEYS = ['modified', 'modified_gmt'];
 // ---- snippets -------------------------------------------------------------------------------
-// `description` is dropped: `snippet push` overwrites it with "Imported from <path>" on every
-// push and `loadSnippets` never reads it back, so it is not part of the synced state. `id`
-// becomes the map key. `code` has its leading `<?php` stripped on both sides: `snippet pull`
-// re-adds it to PHP files for editor friendliness, WordPress stores only the body.
+// `description` is dropped: a sidecar without one gets "Imported from <path>" on push, so
+// comparing it would flag every such snippet as drifted. `id` becomes the map key. A PHP
+// snippet's `code` has its leading `<?php` stripped on both sides: `snippet pull` re-adds it
+// for editor friendliness, WordPress stores only the body. Other types keep it, it's content.
 function canonicalSnippet(snippet) {
     return {
         active: snippet.active,
-        code: stripPhpOpeningTag(snippet.code),
+        code: snippet.type === 'php' ? stripPhpOpeningTag(snippet.code) : snippet.code,
         insertMethod: snippet.insertMethod,
         location: snippet.location,
         name: snippet.name,

package/dist/lib/rollback-command.js

@@ -126,8 +126,15 @@ export function resourceRollbackCommand(resource, options) {
                 // commands/snippet/push.ts's `static args`), not a --path flag. --env/--yes: the
                 // production guard and the drift confirmation above already covered what the delegated
                 // push's own guard would ask again, same reasoning as the top-level `lps push`
-                // delegating to each resource's push command in commands/push.ts.
-                await this.config.runCommand(`${command.replaceAll(' ', ':')}:push`, [tmpDir, '--env', this.siteConfig.name, '--yes']);
+                // delegating to each resource's push command in commands/push.ts. --overwrite: the drift
+                // check above is the same question as the push's outside-edit check, already answered.
+                await this.config.runCommand(`${command.replaceAll(' ', ':')}:push`, [
+                    tmpDir,
+                    '--env',
+                    this.siteConfig.name,
+                    '--yes',
+                    '--overwrite',
+                ]);
             }
             finally {
                 // A cleanup failure here must never hide a real error from the push above: warn about

package/dist/lib/validate-local.js

@@ -178,12 +178,18 @@ function checkLoopressJson(localConfig, problems) {
     if (plugins === undefined)
         return;
     if (typeof plugins !== 'object' || plugins === null || Array.isArray(plugins)) {
-        problems.push({ file: 'loopress.json', message: '"plugins" must be an object of slug -> version string' });
+        problems.push({ file: 'loopress.json', message: '"plugins" must be an object of slug -> version string or {version, active}' });
         return;
     }
     for (const [slug, version] of Object.entries(plugins)) {
-        if (typeof version !== 'string')
-            problems.push({ file: 'loopress.json', message: `plugin "${slug}" must map to a string` });
+        // The object form is what `plugin pull` writes for a plugin installed but inactive (see PluginPin).
+        const isPin = typeof version === 'string' ||
+            (typeof version === 'object' &&
+                version !== null &&
+                typeof version.version === 'string' &&
+                ['boolean', 'undefined'].includes(typeof version.active));
+        if (!isPin)
+            problems.push({ file: 'loopress.json', message: `plugin "${slug}" must map to a version string or {version, active}` });
     }
 }
 async function checkSnippets(dir, problems) {

package/dist/lib/wp-client.js

@@ -159,8 +159,21 @@ export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     if (err.name === 'TimeoutError') {
         return `Request timed out after ${timeoutMs / 1000}s on ${url}. Is the site reachable?`;
     }
-    return `Request to ${url} failed: ${err.message ?? String(error)}`;
+    const reason = err.code ? NETWORK_ERROR_HINTS[err.code] : undefined;
+    // The site, not the endpoint: every resource fails the same way when the site is down, so
+    // `lps diff` can print it once (see DiffCommand.report).
+    if (reason)
+        return `Could not reach ${new URL(url).origin}: ${reason}. Run \`lps doctor\` to check the environment.`;
+    // Node leaves `message` empty on some network errors (an AggregateError over IPv4 + IPv6):
+    // fall back to the error code so the reason is never blank.
+    return `Request to ${url} failed: ${err.message?.length ? err.message : (err.code ?? String(error))}`;
 }
+const NETWORK_ERROR_HINTS = {
+    ECONNREFUSED: 'connection refused, the site may be down',
+    ECONNRESET: 'connection reset by the server',
+    ENOTFOUND: 'host not found, check the URL',
+    ETIMEDOUT: 'connection timed out',
+};
 function extractLoopressError(body) {
     if (!body)
         return undefined;

package/dist/types/snippet.d.ts

@@ -2,6 +2,7 @@ import { type SnippetInsertMethod, type SnippetLocation, type SnippetType } from
 export type Snippet = {
     active: boolean;
     code: string;
+    description?: string;
     id?: number;
     insertMethod: SnippetInsertMethod;
     location: SnippetLocation;