@loopress/cli 0.24.0 → 0.25.0

package/dist/lib/local-callback-server.js

@@ -1,4 +1,5 @@
 import { Buffer } from 'node:buffer';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import { openBrowser } from './open-browser.js';
 async function readBody(req) {
@@ -10,12 +11,31 @@ async function readBody(req) {
 function parseFormData(body) {
     return Object.fromEntries(new URLSearchParams(body));
 }
+/** Constant-time compare that also tolerates a length mismatch without throwing. */
+function safeEqual(a, b) {
+    const bufferA = Buffer.from(a);
+    const bufferB = Buffer.from(b);
+    return bufferA.length === bufferB.length && timingSafeEqual(bufferA, bufferB);
+}
 /**
  * Sends the user to a URL in their browser and catches the resulting redirect on a short-lived
  * local server; this factors out the server setup, timeout, and browser-opening boilerplate.
+ *
+ * The loopback server is unauthenticated, so any local process or web page open during the wait
+ * could otherwise POST forged credentials to it (RFC 8252 section 8.9). Two guards close that:
+ *
+ * - a 32-byte `state` generated here, threaded into the authorize URL by `buildUrl`, and required
+ *   back (constant-time compare) on any request that carries credentials;
+ * - an `Origin` allowlist: a browser sends `Origin` on the relay's cross-site form POST, so a
+ *   stray page's POST (carrying its own origin) is rejected. Top-level navigations send no
+ *   `Origin` and are allowed, which is why `state` is the primary control.
+ *
+ * The first request that looks like a callback (valid or not) shuts the server down, so a
+ * failed guess gets no second try within the window.
  */
 export async function waitForLocalCallback(options) {
     const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
+    const state = randomBytes(32).toString('hex');
     return new Promise((resolve, reject) => {
         function finish(res, page) {
             res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
@@ -23,10 +43,29 @@ export async function waitForLocalCallback(options) {
             clearTimeout(timer);
             server.close();
         }
+        function rejectRequest(res, message) {
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            res.end(message);
+            clearTimeout(timer);
+            server.close();
+            reject(new Error(message));
+        }
         async function handleIncoming(req, res) {
             try {
                 const url = new URL(req.url ?? '/', 'http://localhost');
                 const body = req.method === 'POST' ? parseFormData(await readBody(req)) : {};
+                const looksLikeCallback = url.searchParams.has('state') || Object.keys(body).length > 0;
+                if (looksLikeCallback) {
+                    const { origin } = req.headers;
+                    if (origin !== undefined && !options.allowedOrigins.includes(origin)) {
+                        rejectRequest(res, 'Rejected a cross-origin request to the login callback server.');
+                        return;
+                    }
+                    if (!safeEqual(url.searchParams.get('state') ?? '', state)) {
+                        rejectRequest(res, 'Rejected a login callback with a missing or invalid state value.');
+                        return;
+                    }
+                }
                 options.handleRequest(url, {
                     rejectWithPage(page, error) {
                         finish(res, page);
@@ -61,7 +100,7 @@ export async function waitForLocalCallback(options) {
         }, timeoutMs);
         server.listen(0, '127.0.0.1', () => {
             const { port } = server.address();
-            const targetUrl = options.buildUrl(`http://localhost:${port}`);
+            const targetUrl = options.buildUrl(`http://localhost:${port}`, state);
             options.log(options.openingMessage);
             options.log(`\nIf it doesn't open automatically, visit:\n${targetUrl}\n`);
             openBrowser(targetUrl);

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

@@ -22,12 +22,17 @@ export type PhpFilesResource = {
     pathNoun: string;
     pullDescription: string;
     pushDescription: string;
+    rmDescription: string;
 };
-type PhpFile = {
-    content: string;
+type RemotePhpFile = {
+    content?: string;
+    error?: string;
     filename: string;
+    public?: boolean;
+    revision?: string;
 };
 type PushResult = {
+    pruned: string[];
     pushed: string[];
     status: 'dry-run' | 'success';
 };
@@ -36,6 +41,11 @@ type PullResult = {
     pulled: string[];
     status: 'dry-run' | 'success';
 };
+type RmResult = {
+    filename: string;
+    removed: boolean;
+    status: 'aborted' | 'dry-run' | 'success';
+};
 export type CommandClass<TInstance> = new (argv: string[], config: Config) => TInstance;
 export type PushFilesCommand = Omit<PushCommand, 'run'> & {
     run(): Promise<PushResult>;
@@ -44,11 +54,15 @@ export type PullFilesCommand = Omit<LoopressCommand, 'run'> & {
     run(): Promise<PullResult>;
 };
 export type ListFilesCommand = Omit<LoopressCommand, 'run'> & {
-    run(): Promise<PhpFile[]>;
+    run(): Promise<RemotePhpFile[]>;
+};
+export type RmFilesCommand = Omit<LoopressCommand, 'run'> & {
+    run(): Promise<RmResult>;
 };
 export declare function resourcePushCommand(spec: PhpFilesResource): CommandClass<PushFilesCommand>;
 export declare function resourcePullCommand(spec: PhpFilesResource): CommandClass<PullFilesCommand>;
 export declare function resourceListCommand(spec: PhpFilesResource): CommandClass<ListFilesCommand>;
+export declare function resourceRmCommand(spec: PhpFilesResource): CommandClass<RmFilesCommand>;
 export declare const API_FILES_RESOURCE: PhpFilesResource;
 export declare const HOOK_FILES_RESOURCE: PhpFilesResource;
 export {};

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

@@ -1,4 +1,6 @@
-import { Args } from '@oclif/core';
+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';
@@ -7,13 +9,29 @@ import { resolveResourceDir, RESOURCE_DIR_DEFAULTS } from '../utils/resource-dir
 import { ApiClient } from './api-client.js';
 import { LoopressCommand } from './base.js';
 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)` }) };
 }
@@ -35,35 +53,130 @@ export function resourcePushCommand(spec) {
         static args = pathArg(spec.pathNoun);
         static description = spec.pushDescription;
         static enableJsonFlag = true;
-        static examples = [`$ lps ${spec.cliName} push`, `$ lps ${spec.cliName} push --path ./${RESOURCE_DIR_DEFAULTS[spec.dirKind]}`];
-        static flags = { ...PushCommand.dryRunFlag, ...PushCommand.yesFlag };
+        static examples = [
+            `$ lps ${spec.cliName} push`,
+            `$ lps ${spec.cliName} push --path ./${RESOURCE_DIR_DEFAULTS[spec.dirKind]}`,
+            `$ lps ${spec.cliName} push --prune`,
+        ];
+        static flags = {
+            ...PushCommand.dryRunFlag,
+            ...PushCommand.yesFlag,
+            prune: Flags.boolean({
+                default: false,
+                description: `Delete server-side ${spec.noun}s not present locally after pushing`,
+            }),
+        };
         async run() {
-            const { args } = await this.parse(ResourcePush);
+            const { args, flags } = await this.parse(ResourcePush);
             const { url } = this.siteConfig;
             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 = [];
+            // 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) => {
-                await this.pushFile(file, task);
-                pushed.push(file.filename);
+                this.validateFileLocally(file, task);
             });
             if (this.failedCount > 0) {
                 this.error(`${pluralize(this.failedCount, spec.noun)} failed to push.`);
             }
-            if (this.dryRun)
-                return { pushed, status: 'dry-run' };
+            // 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, 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.`);
-            return { pushed, status: 'success' };
+            return { pruned, pushed, status: 'success' };
         }
         async loadFiles(path) {
             return loadPhpFiles(this, path);
         }
-        async pushFile(file, task) {
+        // 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 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)
+                return [];
+            const summary = `${pluralize(orphans.length, spec.noun)} on ${this.siteConfig.url} not present locally: ${orphans.join(', ')}`;
+            if (this.dryRun) {
+                this.log(`[dry-run] Would prune ${summary}`);
+                return orphans;
+            }
+            if (!this.yes) {
+                if (!isInteractive()) {
+                    const count = pluralize(orphans.length, `server-side ${spec.noun}`);
+                    this.error(`--prune would delete ${count} but stdin is not a TTY. Re-run with --yes to confirm, or without --prune.`);
+                }
+                const ok = await confirm({ default: false, message: `Prune ${summary}?` });
+                if (!ok) {
+                    this.log('Kept the server-side files, nothing pruned.');
+                    return [];
+                }
+            }
+            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);
@@ -74,26 +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;
-            }
-            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}`;
-                }
-            }
-            catch (error) {
-                this.reportTaskFailure(`Failed to push ${file.filename}: ${error.message}`, error, task);
-            }
+            if (task)
+                task.output = `Validated: ${file.filename}`;
         }
     }
     return ResourcePush;
@@ -112,19 +207,28 @@ export function resourcePullCommand(spec) {
             this.log(`Pulling ${spec.label} from ${url}`);
             this.log(`${spec.pathLabel} path: ${path}`);
             const files = await this.wp.get(spec.endpoint);
+            // A file the server would not read back (over the size limit, see LP-SEC-02) arrives
+            // with no content: report it and leave any local copy untouched rather than overwriting
+            // it with nothing.
+            const unreadable = files.filter((file) => typeof file.content !== 'string');
+            for (const file of unreadable) {
+                this.warn(`Skipped ${file.filename}: ${file.error ?? 'the server did not return its content'}`);
+            }
+            const readable = files.filter((file) => typeof file.content === 'string');
             // A `<filename>.php` no longer present remotely was deleted on WordPress (push stays
-            // additive-only, but pull already cleans up locally, same as `snippet pull`).
+            // additive-only, but pull already cleans up locally, same as `snippet pull`). The
+            // unreadable ones still exist remotely, so keep them out of the orphan set.
             const orphans = await findOrphanedFiles(path, new Set(files.map((file) => file.filename)), {
                 extensions: ['.php'],
                 key: basenameKey,
                 recursive: true,
             });
-            const pulled = files.map((file) => file.filename);
-            await this.pullDirectory(path, files, orphans, {
+            const pulled = readable.map((file) => file.filename);
+            await this.pullDirectory(path, readable, orphans, {
                 alwaysCreateDir: true,
-                dryRunMessage: `Would pull ${pluralize(files.length, spec.noun)} to ${path}`,
+                dryRunMessage: `Would pull ${pluralize(readable.length, spec.noun)} to ${path}`,
                 orphanReason: spec.orphanReason,
-                pulledMessage: `Pulled ${pluralize(files.length, spec.noun)} to ${path}`,
+                pulledMessage: `Pulled ${pluralize(readable.length, spec.noun)} to ${path}`,
                 title: (file) => file.filename,
                 async write(file, writeDir) {
                     const filePath = join(writeDir, `${file.filename}.php`);
@@ -156,13 +260,66 @@ export function resourceListCommand(spec) {
             this.log(`Found ${pluralize(files.length, spec.noun)}:`);
             this.log('');
             for (const file of files) {
-                this.log(`  ${file.filename}`);
+                const badges = [file.public ? '[PUBLIC]' : '', file.error ? `(${file.error})` : ''].filter(Boolean).join('  ');
+                this.log(badges ? `  ${file.filename}  ${badges}` : `  ${file.filename}`);
+            }
+            if (files.some((file) => file.public)) {
+                this.log('');
+                this.warn('[PUBLIC] routes run for anyone, with no authentication. Review them.');
             }
             return files;
         }
     }
     return ResourceList;
 }
+export function resourceRmCommand(spec) {
+    class ResourceRm extends LoopressCommand {
+        static args = {
+            filename: Args.string({
+                description: `The ${spec.noun} to remove, its slug without the .php extension (e.g. "hello" or "invoice-pdf/[order_id]")`,
+                required: true,
+            }),
+        };
+        static description = spec.rmDescription;
+        static enableJsonFlag = true;
+        static examples = [`$ lps ${spec.cliName} rm hello`, `$ lps ${spec.cliName} rm hello --yes`];
+        static flags = { ...LoopressCommand.dryRunFlag, ...LoopressCommand.yesFlag };
+        async run() {
+            const { args } = await this.parse(ResourceRm);
+            const { filename } = args;
+            const { url } = this.siteConfig;
+            if (!spec.filenamePattern.test(filename)) {
+                this.error(`Invalid filename "${filename}": ${spec.invalidFilenameHint}`);
+            }
+            if (this.dryRun) {
+                this.log(`[dry-run] Would remove ${filename} from ${url}`);
+                return { filename, removed: false, status: 'dry-run' };
+            }
+            if (!this.yes) {
+                if (!isInteractive()) {
+                    this.error(`Removing ${filename} needs confirmation. Re-run with --yes.`);
+                }
+                const ok = await confirm({ default: false, message: `Remove ${filename} from ${url}?` });
+                if (!ok) {
+                    this.log('Aborted.');
+                    return { filename, removed: false, status: 'aborted' };
+                }
+            }
+            try {
+                await this.wp.delete(`${spec.endpoint}?filename=${encodeURIComponent(filename)}`);
+            }
+            catch (error) {
+                if (isApplicative404(error, 'File not found')) {
+                    this.error(`${filename} is not on ${url}.`);
+                }
+                throw error;
+            }
+            this.log(`Removed ${filename} from ${url}`);
+            return { filename, removed: true, status: 'success' };
+        }
+    }
+    return ResourceRm;
+}
 export const API_FILES_RESOURCE = {
     // Best-effort report of the current route list to the Loopress cloud, purely for console
     // visibility (US-18): the routes are already live on WordPress by this point, so this can
@@ -195,6 +352,7 @@ export const API_FILES_RESOURCE = {
     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',
 };
 export const HOOK_FILES_RESOURCE = {
     cliName: 'hook',
@@ -213,4 +371,5 @@ export const HOOK_FILES_RESOURCE = {
     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',
 };

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('/'));
+}