@loopress/cli 0.24.1 → 0.26.0

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

@@ -1,5 +1,6 @@
 import { confirm } from '@inquirer/prompts';
 import { Args, Flags } from '@oclif/core';
+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';
@@ -11,12 +12,26 @@ import { basenameKey, findOrphanedFiles } from './find-orphaned-files.js';
 import { isInteractive } from './interactive.js';
 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';
 // 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;
+// 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
+// resource-state.ts), the same string AbstractFilesController::push_file() hashes server-side to
+// produce the `revision` it returns, so hashing it here the same way (sha256, hex) reproduces
+// that server revision with no extra network round trip and no need for the server to echo a
+// `revision` field back through the list endpoint for the CLI to consume. A filename absent from
+// `beforeState` (a new file, or `beforeState` itself unavailable, e.g. a dry run or a failed
+// remote read) has nothing to condition on: pushFile falls back to today's unconditional create.
+function expectedRevisionFor(beforeState, filename) {
+    const content = beforeState?.get(filename);
+    return typeof content === 'string' ? createHash('sha256').update(content, 'utf8').digest('hex') : undefined;
+}
 function pathArg(pathNoun) {
     return { path: Args.string({ description: `Path to ${pathNoun} (overrides project config)` }) };
 }
@@ -57,25 +72,34 @@ export function resourcePushCommand(spec) {
             const path = resolveResourceDir(spec.dirKind, this.localConfig, args.path);
             this.log(`Pushing ${spec.label} to ${url}`);
             this.log(`${spec.pathLabel} path: ${path}`);
+            const provider = getResourceStateProvider(spec.cliName);
+            const beforeState = await this.captureBeforePushState(provider, path);
             const files = await this.loadFiles(path);
             this.log(`Found ${pluralize(files.length, spec.noun)} to push`);
-            const pushed = [];
-            const publicRoutes = [];
+            // Local, network-free checks only (filename shape, the declare(strict_types=1) guard):
+            // catches a bad file before anything is staged on WordPress, same as before #236. The
+            // actual write is no longer per-file here, it's the single atomic batch request below.
             await this.runPushTasks(files, (file) => file.filename, async (file, task) => {
-                const result = await this.pushFile(file, task);
-                pushed.push(file.filename);
-                if (result?.public)
-                    publicRoutes.push(file.filename);
+                this.validateFileLocally(file, task);
             });
             if (this.failedCount > 0) {
                 this.error(`${pluralize(this.failedCount, spec.noun)} failed to push.`);
             }
-            for (const route of publicRoutes) {
-                this.warn(`${route}: PUBLIC route, no authentication required. Anyone on the internet can call it. See https://loopress.dev/api/routes/#authentication-and-permissions`);
+            // Resolved before the batch request: which files to prune is a local decision (a GET plus
+            // confirmation), but their removal itself happens inside the same atomic swap as the push
+            // below, not as separate DELETE calls, so a mid-push failure can't remove server-side
+            // 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' };
             }
-            const pruned = flags.prune ? await this.prune(new Set(files.map((file) => file.filename))) : [];
-            if (this.dryRun)
-                return { pruned, pushed, status: 'dry-run' };
+            const { pruned, pushed } = files.length === 0 && pruneList.length === 0
+                ? { pruned: [], pushed: [] }
+                : await this.pushBatch(files, pruneList, beforeState);
+            await this.writeAfterPushSnapshot(provider, path, beforeState);
             await this.recordSuccess();
             await spec.afterPush?.({ filenames: pushed, siteConfig: this.siteConfig });
             this.log(`All ${spec.label} pushed.`);
@@ -84,12 +108,52 @@ export function resourcePushCommand(spec) {
         async loadFiles(path) {
             return loadPhpFiles(this, path);
         }
+        // One request stages every file and every pruned filename, then swaps them all into place
+        // together (#236): a failure anywhere in the batch (a stale expectedRevision, a class
+        // collision, a syntax error) leaves WordPress completely unchanged, not partially pushed.
+        async pushBatch(files, pruneList, beforeState) {
+            const body = {
+                files: files.map((file) => {
+                    const entry = { content: file.content, filename: file.filename };
+                    // `beforeState` was read once, at the start of this push run (see `expectedRevisionFor`
+                    // above): there is no per-file GET endpoint to re-read it right before this batch the
+                    // way `option push` does. Sent back as `expectedRevision`, WordPress still refuses the
+                    // whole batch (412) if something changed the file in between, instead of silently
+                    // overwriting it (#234); the vulnerable window is this run's own duration rather than a
+                    // single request's, wider than option's but still far smaller than not checking at all.
+                    const expectedRevision = expectedRevisionFor(beforeState, file.filename);
+                    if (expectedRevision !== undefined)
+                        entry.expectedRevision = expectedRevision;
+                    return entry;
+                }),
+                prune: pruneList,
+            };
+            let result;
+            try {
+                result = await this.wp.post(`${spec.endpoint}/batch`, body);
+            }
+            catch (error) {
+                this.error(`Push failed, nothing was changed on ${this.siteConfig.url}: ${error.message}`);
+            }
+            for (const file of result.files) {
+                this.log(file.syntax_check === 'skipped'
+                    ? `Pushed: ${file.filename} (syntax check skipped, unavailable on this host)`
+                    : `Pushed: ${file.filename}`);
+                if (file.public) {
+                    this.warn(`${file.filename}: PUBLIC route, no authentication required. Anyone on the internet can call it. See https://loopress.dev/api/routes/#authentication-and-permissions`);
+                }
+            }
+            for (const filename of result.pruned)
+                this.log(`Pruned: ${filename}`);
+            return { pruned: result.pruned, pushed: result.files.map((file) => file.filename) };
+        }
         // Mirror of `pull`'s local orphan cleanup, aimed at the server: any file on WordPress with
-        // no local counterpart is deleted. Opt-in (`--prune`) because it removes code from a live
-        // site. In a non-TTY without `--yes` it refuses rather than prunes: a stray local path in
-        // CI must not silently wipe production routes, and unlike `pull`'s local deletions these
-        // are not recoverable from the repo.
-        async prune(localFilenames) {
+        // no local counterpart is a candidate for removal. Opt-in (`--prune`) because it removes
+        // code from a live site. In a non-TTY without `--yes` it refuses rather than prunes: a stray
+        // local path in CI must not silently wipe production routes, and unlike `pull`'s local
+        // deletions these are not recoverable from the repo. Only decides *which* filenames to
+        // prune; pushBatch() is what actually removes them, atomically alongside the push.
+        async resolvePruneList(localFilenames) {
             const remote = await this.wp.get(spec.endpoint);
             const orphans = remote.map((file) => file.filename).filter((name) => !localFilenames.has(name));
             if (orphans.length === 0)
@@ -110,17 +174,9 @@ export function resourcePushCommand(spec) {
                     return [];
                 }
             }
-            // Sequential, like runPushTasks: keeps the "Pruned: …" lines ordered and the WordPress
-            // writes serial.
-            const deleted = [];
-            for (const filename of orphans) {
-                await this.wp.delete(`${spec.endpoint}?filename=${encodeURIComponent(filename)}`);
-                this.log(`Pruned: ${filename}`);
-                deleted.push(filename);
-            }
-            return deleted;
+            return orphans;
         }
-        async pushFile(file, task) {
+        validateFileLocally(file, task) {
             if (!spec.filenamePattern.test(file.filename)) {
                 const message = `Invalid filename "${file.filename}": ${spec.invalidFilenameHint}`;
                 this.reportTaskFailure(message, new Error(message), task);
@@ -131,27 +187,8 @@ export function resourcePushCommand(spec) {
                 const message = `${file.filename}.php: "declare(strict_types=1);" ${reason}, it must appear exactly once as the first statement`;
                 this.reportTaskFailure(message, new Error(message), task);
             }
-            if (this.dryRun) {
-                if (task)
-                    task.output = `[dry-run] Would push: ${file.filename}`;
-                return undefined;
-            }
-            try {
-                const result = await this.wp.put(spec.endpoint, {
-                    content: file.content,
-                    filename: file.filename,
-                });
-                if (task) {
-                    task.output =
-                        result.syntax_check === 'skipped'
-                            ? `Pushed: ${file.filename} (syntax check skipped, unavailable on this host)`
-                            : `Pushed: ${file.filename}`;
-                }
-                return result;
-            }
-            catch (error) {
-                this.reportTaskFailure(`Failed to push ${file.filename}: ${error.message}`, error, task);
-            }
+            if (task)
+                task.output = `Validated: ${file.filename}`;
         }
     }
     return ResourcePush;

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

@@ -1,7 +1,10 @@
 import { LoopressCommand } from './base.js';
+import { type ResourceState } from './diff-state.js';
+import { type ResourceStateProvider } from './resource-state.js';
 export declare abstract class PushCommand extends LoopressCommand {
     protected failedCount: number;
     private refusedByGuard;
+    protected captureBeforePushState(provider: ResourceStateProvider, dir: string): Promise<ResourceState | undefined>;
     catch(err: Error): Promise<void>;
     protected guardProductionPush(): Promise<void>;
     init(): Promise<void>;
@@ -13,4 +16,5 @@ export declare abstract class PushCommand extends LoopressCommand {
     protected runPushTasks<T>(items: T[], label: (item: T) => string, task: (item: T, task?: {
         output: string;
     }) => Promise<void>): Promise<void>;
+    protected writeAfterPushSnapshot(provider: ResourceStateProvider, dir: string, beforeState: ResourceState | undefined): Promise<void>;
 }

package/dist/lib/push-command.js

@@ -1,14 +1,35 @@
 import got from 'got';
 import { Listr } from 'listr2';
+import { resolve } from 'node:path';
 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';
 export class PushCommand extends LoopressCommand {
     failedCount = 0;
     // Refusals of the production guard never reach the site, so they must not pollute the
     // deployment history with failure records.
     refusedByGuard = false;
+    // Reads `provider`'s remote state right before a real push, for `writeAfterPushSnapshot` to
+    // pair with the actual post-push remote state once the push completes. A dry run changes
+    // nothing, so there is nothing to snapshot. Best-effort: a read failure (the site briefly
+    // unreachable) must never block the push itself, the same "never interrupt the push flow"
+    // stance recordDeployment takes; `undefined` tells `writeAfterPushSnapshot` there is no
+    // restore point to complete.
+    async captureBeforePushState(provider, dir) {
+        if (this.dryRun)
+            return undefined;
+        try {
+            return await provider.remote(this.wp, (message) => {
+                this.warn(message);
+            }, dir);
+        }
+        catch (error) {
+            this.warn(`Could not read remote state for a rollback snapshot: ${error.message}`);
+            return undefined;
+        }
+    }
     async catch(err) {
         if (!this.dryRun && !this.refusedByGuard && this.siteConfig) {
             await this.recordDeployment('failure');
@@ -73,4 +94,32 @@ export class PushCommand extends LoopressCommand {
             title: `Push ${label(item)}`,
         })), { concurrent: false, exitOnError: false, renderer: this.jsonEnabled() ? 'silent' : 'default' }).run();
     }
+    // Pairs `beforeState` (from captureBeforePushState, read before this push touched anything)
+    // with a fresh remote read taken right after the push, and writes both as one rollback
+    // snapshot. Reading the after-state from WordPress itself, rather than assuming it matches
+    // the local files that were pushed, is what keeps this correct for every resource's own
+    // partial-push semantics: a readonly option skipped by `option push`, a snippet or SEO
+    // redirect that gets a server-assigned id on create, a theme-styles push that only touches the
+    // active stylesheet, an API/hook push that leaves server-side files alone unless `--prune`.
+    // `lps <resource> rollback`'s drift check compares the environment's state at rollback time
+    // against exactly this after-state, so it has to be what actually landed, not what was sent.
+    async writeAfterPushSnapshot(provider, dir, beforeState) {
+        if (!beforeState || this.dryRun)
+            return;
+        try {
+            const afterState = await provider.remote(this.wp, (message) => {
+                this.warn(message);
+            }, dir);
+            await writeSnapshot({
+                afterState,
+                beforeState,
+                environment: this.siteConfig.name,
+                resource: provider.resource,
+                rootDir: resolve(process.cwd(), this.rootDir),
+            });
+        }
+        catch (error) {
+            this.warn(`Could not save a rollback snapshot after this push: ${error.message}`);
+        }
+    }
 }

package/dist/lib/readdir-tolerant.d.ts

@@ -4,3 +4,4 @@ export declare function readdirTolerant(dir: string, options: {
     recursive?: boolean;
     withFileTypes: true;
 }): Promise<Dirent[]>;
+export declare function walkFiles(dir: string): Promise<string[]>;

package/dist/lib/readdir-tolerant.js

@@ -1,4 +1,5 @@
 import { readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
 export async function readdirTolerant(dir, options) {
     try {
         return options?.withFileTypes
@@ -11,3 +12,14 @@ export async function readdirTolerant(dir, options) {
         throw error;
     }
 }
+// Every file under `dir`, at any depth, as a path relative to `dir`. Always '/'-joined,
+// never the OS separator: callers match these identities against server-sent filenames
+// (which are always '/'-joined) or embed them in an API payload, so a Windows run must
+// produce the exact same strings as a POSIX one. ENOENT on `dir` itself yields no files,
+// same tolerance as readdirTolerant.
+export async function walkFiles(dir) {
+    const entries = await readdirTolerant(dir, { recursive: true, withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(dir, join(entry.parentPath, entry.name)).split(sep).join('/'));
+}

package/dist/lib/resource-state.js

@@ -2,9 +2,12 @@ import { readFile } from 'node:fs/promises';
 import { basename, join, relative, sep } from 'node:path';
 import { ACF_OBJECT_TYPES, acfEndpoint, getAcfKey } from '../utils/acf-format.js';
 import { FORM_ENDPOINT, getFormId } from '../utils/form-format.js';
+import { getMenuSlug, MENU_ENDPOINT, MENU_LOCATIONS_ENDPOINT } from '../utils/menu-format.js';
 import { optionEndpoint, parseLocalOption } from '../utils/option-format.js';
+import { formatPageProblems, PAGES_ENDPOINT, readLocalPages } from '../utils/page-format.js';
 import { DEFAULT_POST_TYPES, SEO_REDIRECTS_ENDPOINT, SEO_SETTINGS_ENDPOINT, seoPostMetaEndpoint, } from '../utils/seo-format.js';
 import { normalizeSnippet, SNIPPETS_ENDPOINT, stripPhpOpeningTag } from '../utils/snippet-format.js';
+import { canonicalGlobalStyles, getActiveThemeGlobalStyles, globalStylesEndpoint, THEME_STYLES_FILE_SUFFIX, } from '../utils/theme-styles-format.js';
 import { loadFiles } from './load-files.js';
 import { loadSnippets } from './load-snippets.js';
 import { isApplicative404, isNotFoundError } from './wp-client.js';
@@ -192,6 +195,28 @@ const hookProvider = phpFilesProvider({
     resource: 'hook',
     title: 'Hooks',
 });
+// ---- Pages ------------------------------------------------------------------------------
+// Keyed by slug (the page's identity on both sides). `link` is server-derived and never
+// compared. A local problem (a `.php` in pages/, a bad header) fails the whole resource rather
+// than hiding that page, the same stop-everything stance as `page push`.
+function canonicalPage(page) {
+    return { html: page.html, status: page.status, title: page.title };
+}
+const pageProvider = {
+    dirKind: 'page',
+    async local(dir) {
+        const { pages, problems } = await readLocalPages(dir);
+        if (problems.length > 0)
+            throw new Error(formatPageProblems(problems));
+        return new Map(pages.map((page) => [page.slug, canonicalPage(page)]));
+    },
+    async remote(wp) {
+        const pages = await wp.get(PAGES_ENDPOINT);
+        return new Map(pages.map((page) => [page.slug, canonicalPage(page)]));
+    },
+    resource: 'page',
+    title: 'Pages',
+};
 // ---- SEO --------------------------------------------------------------------------------
 function canonicalRedirect(redirect) {
     return omit(redirect, REDIRECT_VOLATILE_KEYS);
@@ -239,12 +264,16 @@ const seoProvider = {
     },
     async remote(wp, onWarn) {
         const state = new Map();
-        const settings = await wp.get(SEO_SETTINGS_ENDPOINT);
+        // `revision` (#234) is dropped from both, same as optionsProvider.remote() does for
+        // RemoteOption.revision below: it's bookkeeping for the conditional-write precondition, not
+        // configuration, and comparing it here would flag drift whenever the mere act of reading
+        // changed nothing meaningful.
+        const { settings } = await wp.get(SEO_SETTINGS_ENDPOINT);
         state.set('settings', settings);
         for (const postType of DEFAULT_POST_TYPES) {
             const posts = await wp.get(seoPostMetaEndpoint(postType));
-            for (const post of posts)
-                state.set(`post-meta/${postType}/${post.slug}`, post);
+            for (const { meta, slug, title } of posts)
+                state.set(`post-meta/${postType}/${slug}`, { meta, slug, title });
         }
         // Redirects are a RankMath-only feature; on Yoast the endpoint 404s, same graceful skip
         // as `seo pull`.
@@ -264,6 +293,55 @@ const seoProvider = {
     resource: 'seo',
     title: 'SEO',
 };
+// ---- Menus --------------------------------------------------------------------------------
+// Every item's post_type/taxonomy target is already resolved to `object`/`objectSlug` by the
+// REST layer (MenuService), never a raw `_menu_item_object_id`, so the exported tree is already
+// portable and compared as-is. `warnings` is diagnostic (a dangling item, an off-environment
+// custom URL, ...), not tracked configuration, so it's dropped before comparing, the same
+// "volatile key" treatment ACF/forms/redirects give their own server-computed fields. `revision`
+// (#234) is bookkeeping for menu push's conditional-write precondition, not tracked configuration
+// either: it's a pure hash of name + items, so it never disagrees when they don't, but a local
+// file pulled before this field existed simply wouldn't have it, which must never show up as
+// drift on its own.
+const MENU_VOLATILE_KEYS = ['revision', 'warnings'];
+// The reserved local filename for menu locations, see commands/menu/pull.ts.
+const MENU_LOCATIONS_FILE = 'menu-locations';
+function canonicalMenu(menu) {
+    return omit(menu, MENU_VOLATILE_KEYS);
+}
+const menuProvider = {
+    dirKind: 'menu',
+    async local(dir, onWarn) {
+        const state = new Map();
+        const entries = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse: (raw, filePath) => ({ file: basename(filePath, '.json'), value: readJson(raw) }),
+        });
+        for (const { file, value } of entries) {
+            if (file === MENU_LOCATIONS_FILE) {
+                state.set(MENU_LOCATIONS_FILE, value);
+                continue;
+            }
+            const slug = getMenuSlug(value) ?? `local:${file}`;
+            state.set(`menu/${slug}`, canonicalMenu(value));
+        }
+        return state;
+    },
+    async remote(wp) {
+        const state = new Map();
+        const menus = await wp.get(MENU_ENDPOINT);
+        for (const menu of menus) {
+            const slug = getMenuSlug(menu);
+            if (slug !== null)
+                state.set(`menu/${slug}`, canonicalMenu(menu));
+        }
+        state.set(MENU_LOCATIONS_FILE, await wp.get(MENU_LOCATIONS_ENDPOINT));
+        return state;
+    },
+    resource: 'menu',
+    title: 'Menus',
+};
 // ---- Options ------------------------------------------------------------------------------
 // Unlike every provider above, remote() has no "everything" endpoint to read: GET /options only
 // lists names, never values (by design, see OptionsController), so both sides compare exactly
@@ -310,14 +388,49 @@ const optionsProvider = {
     resource: 'option',
     title: 'Options',
 };
+// ---- Theme styles (Global Styles) ----------------------------------------------------------
+// Local files are named `<stylesheet>-global-styles.json`, keyed by stylesheet so a directory
+// that has accumulated files from more than one previously-active theme still compares each one
+// individually rather than colliding on a single key.
+const themeStylesProvider = {
+    dirKind: 'themeStyles',
+    async local(dir, onWarn) {
+        const entries = await loadFiles(dir, {
+            extension: '.json',
+            onSkip: onWarn,
+            parse(raw, filePath) {
+                const name = basename(filePath);
+                const stylesheet = name.endsWith(THEME_STYLES_FILE_SUFFIX) ? name.slice(0, -THEME_STYLES_FILE_SUFFIX.length) : basename(filePath, '.json');
+                return { stylesheet, value: readJson(raw) };
+            },
+        });
+        const state = new Map();
+        for (const { stylesheet, value } of entries)
+            state.set(stylesheet, canonicalGlobalStyles(value));
+        return state;
+    },
+    // Only the active theme's Global Styles are compared (see theme-styles-format.ts): a classic
+    // active theme has no Styles screen at all, surfaced here as a normal provider error, the same
+    // "inconclusive for this resource" treatment DiffCommand gives any other fetch failure.
+    async remote(wp) {
+        const { id, stylesheet } = await getActiveThemeGlobalStyles(wp);
+        const item = await wp.get(globalStylesEndpoint(id));
+        return new Map([[stylesheet, canonicalGlobalStyles(item)]]);
+    },
+    resource: 'theme-styles',
+    title: 'Theme styles',
+};
 export const RESOURCE_STATE_PROVIDERS = [
     snippetProvider,
     formProvider,
     acfProvider,
     apiProvider,
     hookProvider,
+    pageProvider,
     seoProvider,
+    menuProvider,
     optionsProvider,
+    themeStylesProvider,
 ];
 export function getResourceStateProvider(resource) {
     const provider = RESOURCE_STATE_PROVIDERS.find((candidate) => candidate.resource === resource);

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

@@ -0,0 +1,21 @@
+import { LoopressCommand } from './base.js';
+import { type SnapshotSummary } from './snapshot-store.js';
+export type RollbackResult = {
+    drift?: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+    };
+    id?: string;
+    restored?: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+    };
+    snapshots?: SnapshotSummary[];
+    status: 'dry-run' | 'listed' | 'no-op' | 'success';
+};
+export declare function resourceRollbackCommand(resource: string, options: {
+    description: string;
+    pathNoun: string;
+}): typeof LoopressCommand;