@loopress/cli 0.27.0 → 0.29.0

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

@@ -0,0 +1,123 @@
+import { Flags } from '@oclif/core';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { confirmUninstall } from '../../../lib/interactive.js';
+import { PushCommand } from '../../../lib/push-command.js';
+import { isNotFoundError } from '../../../lib/wp-client.js';
+import { isDowngrade, parseCollisions, SYNC_TIMEOUT_MS } from '../../../utils/plugin-sync.js';
+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 enableJsonFlag = true;
+    static examples = ['$ lps theme version push', '$ lps theme version push --force'];
+    static flags = {
+        ...PushCommand.dryRunFlag,
+        ...PushCommand.yesFlag,
+        force: Flags.boolean({ default: false, description: 'Allow downgrades and take over themes installed outside Loopress' }),
+    };
+    async run() {
+        const { flags } = await this.parse(Push);
+        const { force } = flags;
+        if (existsSync(join(process.cwd(), this.rootDir, 'composer.json'))) {
+            this.warn('This project has a composer.json, which is authoritative. Run `lps composer push` instead.');
+            return { ...IN_SYNC, status: 'composer-managed' };
+        }
+        const manifest = this.localConfig.themes ?? {};
+        if (Object.keys(manifest).length === 0) {
+            this.error('No themes found in loopress.json. Run `lps theme version pull` first.');
+        }
+        this.log(`Pushing themes to ${this.siteConfig.url}`);
+        const raw = await this.wp.get('wp/v2/themes');
+        const installed = parseInstalledThemes(raw);
+        const managed = lockedWpackagistSlugs(await this.fetchInstanceLock(), 'theme');
+        const diff = diffThemes(manifest, installed, managed);
+        this.guardForce(diff, force);
+        // Uninstalling the theme WordPress is currently rendering leaves the site with no active
+        // theme, which is a hard fatal. --force does not override this: switch the active theme
+        // on the site first, then the removal is safe. A --force takeover of a collision hits the
+        // same fatal: the server moves the existing folder out of the way before reinstalling it,
+        // so the active theme is briefly missing either way, an active collision is just as
+        // dangerous as an active removal.
+        const activeRemoval = [...diff.toRemove, ...diff.collisions.map((c) => c.slug)].find((slug) => installed.find((t) => t.slug === slug)?.active);
+        if (activeRemoval) {
+            this.error(`Refusing to uninstall "${activeRemoval}": it is the site's active theme. ` +
+                'Switch the site to another theme, then re-run to remove it.');
+        }
+        // A "latest" pin never shows as drift, but its newest upstream release may have moved, so
+        // a push must still run `composer update` to pick it up.
+        const hasLatestPin = Object.values(manifest).includes('latest');
+        if (!hasLatestPin && isNoop(diff)) {
+            this.log('Everything is already in sync.');
+            return { ...IN_SYNC };
+        }
+        if (isNoop(diff))
+            this.log('Refreshing themes pinned to "latest" to their newest releases.');
+        for (const a of diff.toInstall)
+            this.log(`  + ${a.slug} ${a.version}`);
+        for (const p of diff.toPin)
+            this.log(`  ~ ${p.slug} ${p.from} to ${p.to}`);
+        for (const s of diff.toRemove)
+            this.log(`  - ${s}`);
+        for (const c of diff.collisions)
+            this.log(`  ! ${c.slug} (take over)`);
+        if (this.dryRun)
+            return result(diff, 'dry-run', diff.toRemove, true);
+        if (!(await confirmUninstall(diff.toRemove, this.yes)))
+            this.error('Aborted.');
+        const response = await this.sync(manifest, force);
+        if (response.output.trim())
+            this.log(response.output.trim());
+        this.log('Themes synced.');
+        await this.recordSuccess();
+        return result(diff, 'success', response.removed ?? diff.toRemove, force);
+    }
+    async fetchInstanceLock() {
+        try {
+            const { composerLock } = await this.wp.get('loopress/v1/composer/lock');
+            return composerLock;
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
+        }
+    }
+    guardForce(diff, force) {
+        if (force)
+            return;
+        if (diff.collisions.length > 0) {
+            const list = diff.collisions.map((c) => `${c.slug} (${c.installedVersion})`).join(', ');
+            this.error(`${list} installed outside Loopress. Re-run with --force to take them over, or remove them from loopress.json.`);
+        }
+        const downgrades = diff.toPin.filter((p) => isDowngrade(p.from, p.to));
+        if (downgrades.length > 0) {
+            const list = downgrades.map((p) => `${p.slug} ${p.from} to ${p.to}`).join(', ');
+            this.error(`Refusing to downgrade: ${list}. Re-run with --force.`);
+        }
+    }
+    async sync(manifest, force) {
+        try {
+            return await this.wp.post('loopress/v1/composer/sync', { force, intent: { themes: manifest }, lock: null }, { timeoutMs: SYNC_TIMEOUT_MS });
+        }
+        catch (error) {
+            if (parseCollisions(error)) {
+                this.error('The site rejected the push: themes installed outside Loopress. Re-run with --force.');
+            }
+            throw error;
+        }
+    }
+}
+function isNoop(diff) {
+    return (diff.toInstall.length === 0 && diff.toPin.length === 0 && diff.toRemove.length === 0 && diff.collisions.length === 0);
+}
+function result(diff, status, removed, includeCollisions) {
+    const collisionSlugs = includeCollisions ? diff.collisions.map((c) => c.slug) : [];
+    return {
+        installed: [...diff.toInstall.map((a) => a.slug), ...collisionSlugs],
+        pinned: diff.toPin.map((p) => p.slug),
+        removed,
+        status,
+    };
+}

package/dist/hooks/finally.d.ts

@@ -1,3 +1,4 @@
-import type { Hook } from '@oclif/core';
+import { type Hook } from '@oclif/core';
 declare const hook: Hook.Finally;
+export declare function dropHttpCause(error: Error): void;
 export default hook;

package/dist/hooks/finally.js

@@ -1,3 +1,5 @@
+import { settings } from '@oclif/core';
+import { RequestError } from 'got';
 import { isTelemetryDisabled, redactArgv, resolveEnvironment, runtimeContext, scrubEvent, SENTRY_DSN, } from '../lib/sentry.js';
 // oclif has no `command_error` hook (checked @oclif/core@4.11.11's hooks.d.ts). `finally`
 // is the closest equivalent: it always runs at the end of the CLI lifecycle and carries
@@ -7,8 +9,15 @@ import { isTelemetryDisabled, redactArgv, resolveEnvironment, runtimeContext, sc
 // It's a heavy module (@opentelemetry deps, import-in-the-middle instrumentation), so loading
 // it eagerly on every command would tax the common case where commands succeed.
 const hook = async function (options) {
-    if (!options.error || isTelemetryDisabled())
+    if (!options.error)
         return;
+    if (!isTelemetryDisabled())
+        await report(this, options);
+    // After the report, so Sentry still gets the whole chain. LPS_DEBUG=1 keeps it on screen too.
+    if (!settings.debug)
+        dropHttpCause(options.error);
+};
+async function report(context, options) {
     try {
         const Sentry = await import('@sentry/node');
         Sentry.init({
@@ -17,7 +26,7 @@ const hook = async function (options) {
             beforeSend: scrubEvent,
             dsn: SENTRY_DSN,
             environment: resolveEnvironment(),
-            release: this.config.version,
+            release: context.config.version,
             // Node defaults `server_name` to os.hostname(), which is often the user's real name
             // (e.g. "jane-doe-macbook-pro"). sendDefaultPii covers IP addresses and similar, off by
             // default but set explicitly since this reports from users' own machines.
@@ -32,7 +41,21 @@ const hook = async function (options) {
         await Sentry.flush(2000);
     }
     catch (error) {
-        this.debug('Failed to report error to Sentry: %O', error);
+        context.debug('Failed to report error to Sentry: %O', error);
     }
-};
+}
+// WpClient and ApiClient already fold what matters of a got error (status, the server's own
+// reason) into their own message, and keep got's error as `cause` for the helpers that read
+// its response. oclif prints every cause after the message, so without this a clear "Request
+// failed (409) on ...: The active theme is not a block theme" ends with "Caused by: HTTPError:
+// Request failed with status code 409 ... Code: ERR_NON_2XX_3XX_RESPONSE", which is what the
+// user remembers. Other causes (a failed plugin install under its fallback advice) stay.
+export function dropHttpCause(error) {
+    for (let current = error; current instanceof Error; current = current.cause) {
+        if (current.cause instanceof RequestError) {
+            delete current.cause;
+            return;
+        }
+    }
+}
 export default hook;

package/dist/lib/api-client.js

@@ -45,7 +45,9 @@ function formatApiError(error, url, timeoutMs) {
     }
     const reason = nestErrorMessage(err.response?.body);
     if (status === 403) {
-        return `Request rejected (${status}) on ${url}: ${reason ?? err.response?.body ?? err.message}`;
+        // An empty body (not just a missing one) falls back to got's message too, never a bare ": ".
+        const body = err.response?.body === '' ? undefined : err.response?.body;
+        return `Request rejected (${status}) on ${url}: ${reason ?? body ?? err.message}`;
     }
     // Any other API refusal (a 400 validation error, a 409 conflict) carries its explanation in
     // the body; got's own message ("Request failed with status code 400") never does.

package/dist/lib/app-build.d.ts

@@ -0,0 +1,5 @@
+declare const PACKAGE_MANAGERS: readonly ["bun", "npm", "pnpm", "yarn"];
+type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+export declare function detectPackageManager(appDir: string, packageManagerField?: string): PackageManager;
+export declare function buildApp(appDir: string, onStart?: (command: string) => void): Promise<string | undefined>;
+export {};

package/dist/lib/app-build.js

@@ -0,0 +1,69 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+// The package managers `lps app push` may spawn. An allowlist, not the raw `packageManager`
+// field: the name ends up as a process to run.
+const PACKAGE_MANAGERS = ['bun', 'npm', 'pnpm', 'yarn'];
+const LOCKFILES = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+    ['package-lock.json', 'npm'],
+];
+// How many trailing lines of build output a failure message carries.
+const OUTPUT_TAIL_LINES = 20;
+// `packageManager` field first (corepack's own source of truth), then the nearest lockfile
+// walking up to the repository root (an app inside a workspace shares the root lockfile),
+// then npm.
+export function detectPackageManager(appDir, packageManagerField) {
+    const fromField = packageManagerField?.split('@', 1)[0];
+    if (PACKAGE_MANAGERS.includes(fromField))
+        return fromField;
+    for (let dir = appDir;; dir = dirname(dir)) {
+        const lockfile = LOCKFILES.find(([file]) => existsSync(join(dir, file)));
+        if (lockfile)
+            return lockfile[1];
+        if (existsSync(join(dir, '.git')) || dirname(dir) === dir)
+            return 'npm';
+    }
+}
+// Runs the app's own `build` script, if its package.json declares one. Returns the command it
+// ran, or undefined when there is nothing to build (no package.json, or no build script: the
+// dist/ folder is then taken as is). Throws with the tail of the output when the build fails,
+// so a broken build never ships the stale dist/ left over from the previous one.
+export async function buildApp(appDir, onStart) {
+    const packageJsonPath = join(appDir, 'package.json');
+    if (!existsSync(packageJsonPath))
+        return undefined;
+    const pkg = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+    if (!pkg.scripts?.build)
+        return undefined;
+    const pm = detectPackageManager(appDir, pkg.packageManager);
+    const command = `${pm} run build`;
+    onStart?.(command);
+    const { code, output } = await new Promise((resolve, reject) => {
+        // Windows resolves `npm` to `npm.cmd`, which only a shell finds. `pm` comes from the
+        // allowlist above, so the shell never sees user input.
+        const child = spawn(pm, ['run', 'build'], { cwd: appDir, shell: process.platform === 'win32' });
+        let out = '';
+        const collect = (chunk) => {
+            out += chunk;
+        };
+        child.stdout.setEncoding('utf8').on('data', collect);
+        child.stderr.setEncoding('utf8').on('data', collect);
+        child.on('error', reject);
+        child.on('close', (exitCode) => {
+            resolve({ code: exitCode, output: out });
+        });
+    });
+    if (code !== 0) {
+        const tail = output.trimEnd().split('\n').slice(-OUTPUT_TAIL_LINES).join('\n');
+        const hint = existsSync(join(appDir, 'node_modules'))
+            ? ''
+            : `\nnode_modules is missing: run \`${pm} install\` in ${appDir} first.`;
+        throw new Error(`\`${command}\` failed (exit code ${code}):\n${tail}${hint}`);
+    }
+    return command;
+}

package/dist/lib/app-manifest.d.ts

@@ -7,8 +7,11 @@ export type AppEntry = {
     scripts: string[];
     styles: string[];
 };
+export declare const CROSS_ORIGIN_POLICIES: readonly ["same-origin", "same-site"];
+export type CrossOriginPolicy = (typeof CROSS_ORIGIN_POLICIES)[number];
 export type AppConfigFile = {
     assetsDir?: string;
+    crossOrigin?: CrossOriginPolicy;
     entry?: AppEntry;
     mountSelector?: string;
     name?: string;
@@ -16,6 +19,7 @@ export type AppConfigFile = {
 };
 export type AppManifest = {
     buildId: string;
+    crossOrigin?: CrossOriginPolicy;
     entry: AppEntry;
     files: AppFile[];
     mountSelector: string;

package/dist/lib/app-manifest.js

@@ -2,6 +2,9 @@ import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
 import { walkFiles } from './readdir-tolerant.js';
+// Cross-Origin-Resource-Policy the server sends with the app's files. Mirrors the server's
+// AppManifest::SUPPORTED_CROSS_ORIGIN; `cross-origin` is the browser default, i.e. the field unset.
+export const CROSS_ORIGIN_POLICIES = ['same-origin', 'same-site'];
 export const APP_CONFIG_FILENAME = 'loopress.app.json';
 const DEFAULT_ASSETS_DIR = 'dist';
 // Static assets a bundler emits, mirrors the server's AppsDirectory::ALLOWED_EXTENSIONS.
@@ -19,7 +22,7 @@ export function isAllowedAsset(relPath) {
 // server would reject, so the push fails locally with a clear message instead of a 400
 // halfway through the upload.
 export async function buildFileList(distDir) {
-    const relPaths = (await walkFiles(distDir)).sort((a, b) => a.localeCompare(b));
+    const relPaths = (await walkFiles(distDir)).toSorted((a, b) => a.localeCompare(b));
     const files = [];
     for (const path of relPaths) {
         if (!isAllowedAsset(path)) {
@@ -34,7 +37,7 @@ export async function buildFileList(distDir) {
 // Used as the enqueue `?ver` (cache busting) and as the build identity in `app list`.
 export function computeBuildId(files) {
     const digest = createHash('sha256');
-    for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+    for (const file of files.toSorted((a, b) => a.path.localeCompare(b.path))) {
         digest.update(`${file.path}:${file.sha256}\n`);
     }
     return digest.digest('hex').slice(0, 12);
@@ -89,6 +92,10 @@ export function parseAppConfig(raw, appDir) {
     if (config.routing !== undefined && config.routing !== 'hash') {
         throw new Error(`${join(appDir, APP_CONFIG_FILENAME)}: routing "${config.routing}" is not supported, only "hash" works without a server rewrite`);
     }
+    if (config.crossOrigin !== undefined && !CROSS_ORIGIN_POLICIES.includes(config.crossOrigin)) {
+        const supported = CROSS_ORIGIN_POLICIES.map((policy) => JSON.stringify(policy)).join(' or ');
+        throw new Error(`${join(appDir, APP_CONFIG_FILENAME)}: crossOrigin "${config.crossOrigin}" is not supported, use ${supported}`);
+    }
     return config;
 }
 // Assembles the full manifest for one app directory: reads loopress.app.json, hashes the
@@ -129,6 +136,7 @@ export async function loadAppManifest(appDir, dirName) {
         distDir,
         manifest: {
             buildId: computeBuildId(files),
+            ...(config.crossOrigin && { crossOrigin: config.crossOrigin }),
             entry,
             files,
             mountSelector: config.mountSelector ?? `#loopress-app-${name}`,

package/dist/lib/base.d.ts

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

package/dist/lib/base.js

@@ -26,6 +26,8 @@ export class LoopressCommand extends Command {
     };
     dryRun = false;
     localConfig = {};
+    // Set by PushCommand's hidden --production-confirmed, see there.
+    productionConfirmed = false;
     projectId;
     siteConfig;
     yes = false;
@@ -35,11 +37,11 @@ export class LoopressCommand extends Command {
     }
     get wp() {
         if (!this.wpClient) {
-            const { token, url } = this.siteConfig;
+            const { name, token, url } = this.siteConfig;
             if (!token) {
                 this.error(`No credentials configured for ${url}. Run \`lps project config\` to add them.`);
             }
-            this.wpClient = new WpClient(url, token);
+            this.wpClient = new WpClient(url, token, name);
         }
         return this.wpClient;
     }
@@ -54,6 +56,7 @@ export class LoopressCommand extends Command {
         }));
         this.dryRun = Boolean(flags['dry-run']);
         this.yes = Boolean(flags.yes);
+        this.productionConfirmed = Boolean(flags['production-confirmed']);
         this.localConfig = await readLocalConfig();
         const resolved = this.resolveEnvironment(flags.env);
         this.siteConfig = resolved.env;
@@ -65,12 +68,21 @@ export class LoopressCommand extends Command {
     // `dryRun` is excluded since rotating writes a new credential, a real side effect a
     // --dry-run run promises not to cause. `Rotate` overrides this to a no-op: its own `run()`
     // already rotates unconditionally, so the background check would only redo the same work.
+    // CI is excluded too: rotating revokes the old password, but a runner's config.json (a CI
+    // secret copy) is thrown away at the end of the job, so every later run would get a 401.
     async maybeAutoRotate() {
         if (this.dryRun)
             return;
         const { token } = this.siteConfig;
         if (!token || !isAppPasswordStale(this.siteConfig.addedAt))
             return;
+        // Set by `lps promote --dry-run` around its delegated pull: a preview must not revoke anything.
+        if (process.env.LOOPRESS_NO_AUTO_ROTATE)
+            return;
+        if (process.env.CI) {
+            this.warn(`The app password for "${this.siteConfig.name}" is older than 90 days. Auto-rotation is skipped in CI, run \`lps project rotate\` where this config.json lives, then update the CI secret.`);
+            return;
+        }
         try {
             const rotated = await rotateAppPassword({ ...this.siteConfig, token });
             this.siteConfig = rotated;

package/dist/lib/bootstrap-full-install.js

@@ -14,24 +14,55 @@ export async function bootstrapLoopressFull(wp, siteUrl, log) {
     const zipPath = await downloadLatestFullZip();
     log('Creating a temporary admin account to install it...');
     const admin = await createTempAdmin(wp);
+    // The temp account is a real administrator; it must never outlive this function, including
+    // when the process is interrupted mid-install (Ctrl-C, or a hung/killed headless browser).
+    // removeTempAdmin() memoises a single deletion so the normal path and either signal handler
+    // all await the same in-flight promise instead of racing or deleting twice.
+    let cleanupPromise;
+    const removeTempAdmin = async () => {
+        cleanupPromise ??= deleteTempAdmin(wp, admin);
+        return cleanupPromise;
+    };
+    const onSignal = (signal) => {
+        // Finish (or start) the deletion, surface a manual-removal hint if it fails since the normal
+        // error path below won't run, then re-raise the signal with our handler gone so Node's
+        // default termination runs with the right exit code.
+        removeTempAdmin()
+            .catch((error) => {
+            log(`Could not remove the temporary admin account "${admin.username}"; remove it manually in wp-admin. (${error.message})`);
+        })
+            .finally(() => {
+            process.removeListener('SIGINT', onSignal);
+            process.removeListener('SIGTERM', onSignal);
+            process.kill(process.pid, signal);
+        });
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
     let installError;
-    try {
-        log('Installing and activating Loopress Full...');
-        await runBrowserInstall(admin, siteUrl, zipPath);
-    }
-    catch (error) {
-        installError = error;
-    }
-    if (!installError) {
-        log('Loopress Full installed and activated.');
-    }
-    log('Removing the temporary admin account...');
     let cleanupError;
     try {
-        await deleteTempAdmin(wp, admin);
+        try {
+            log('Installing and activating Loopress Full...');
+            await runBrowserInstall(admin, siteUrl, zipPath);
+            log('Loopress Full installed and activated.');
+        }
+        catch (error) {
+            installError = error;
+        }
+        log('Removing the temporary admin account...');
+        try {
+            await removeTempAdmin();
+        }
+        catch (error) {
+            cleanupError = error;
+        }
     }
-    catch (error) {
-        cleanupError = error;
+    finally {
+        // Only stop guarding once the deletion has settled: a signal during the removal above must
+        // still trigger (or await) cleanup rather than terminating the process with the account live.
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
     }
     const manualFallback = `Install it manually: upload ${zipPath} at ${siteUrl}/wp-admin/plugin-install.php?tab=upload`;
     if (installError && cleanupError) {

package/dist/lib/dev-watch.d.ts

@@ -1,5 +1,5 @@
 import { type LoopressLocalConfig } from '../utils/loopress-config.js';
-export type ResourceType = 'api' | 'hooks' | 'pages' | 'plugins' | 'snippets';
+export type ResourceType = 'api' | 'hooks' | 'pages' | 'parts' | 'plugins' | 'snippets' | 'templates';
 export declare const RESOURCE_TYPES: ResourceType[];
 export type WatchTarget = {
     commandId: string;

package/dist/lib/dev-watch.js

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { join, sep } from 'node:path';
-export const RESOURCE_TYPES = ['snippets', 'pages', 'api', 'hooks', 'plugins'];
+export const RESOURCE_TYPES = ['snippets', 'templates', 'parts', 'pages', 'api', 'hooks', 'plugins'];
 // `only` narrows the default set, `skip` then removes from whatever that set is, same
 // precedence a combined `--only=a,b --skip=b` reads as: watch a, b, then drop b.
 export function resolveResourceTypes(only, skip = []) {
@@ -18,6 +18,8 @@ export function buildWatchTargets(types, localConfig, cwd) {
         hooks: { commandId: 'hook:push', path: join(rootDir, localConfig.hooksDir ?? 'hooks'), type: 'hooks' },
         pages: { commandId: 'page:push', path: join(rootDir, localConfig.pageDir ?? 'pages'), type: 'pages' },
         plugins: { commandId: 'plugin:push', path: join(cwd, 'loopress.json'), type: 'plugins' },
+        parts: { commandId: 'theme:template:push', path: join(rootDir, localConfig.partDir ?? 'parts'), type: 'parts' },
+        templates: { commandId: 'theme:template:push', path: join(rootDir, localConfig.templateDir ?? 'templates'), type: 'templates' },
         snippets: { commandId: 'snippet:push', path: join(rootDir, localConfig.snippetsDir ?? 'snippets'), type: 'snippets' },
     };
     return types

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

@@ -41,6 +41,7 @@ export declare abstract class DiffCommand extends LoopressCommand {
     private wpForEnvironment;
 }
 export declare function resourceDiffCommand(resource: string, options: {
+    command?: string;
     description: string;
     pathNoun: string;
 }): typeof DiffCommand;

package/dist/lib/diff-command.js

@@ -143,12 +143,14 @@ export class DiffCommand extends LoopressCommand {
         if (!env.token) {
             this.error(`No credentials configured for "${envName}". Run \`lps project config\` to add them.`);
         }
-        return new WpClient(env.url, env.token);
+        return new WpClient(env.url, env.token, env.name);
     }
 }
 // Builds the `lps <resource> diff` command class for one directory-backed resource. They differ
 // only in wording and which provider they target, so the whole body lives here.
+// `command` is the CLI topic when it isn't the resource key (e.g. `theme style` for theme-styles).
 export function resourceDiffCommand(resource, options) {
+    const command = options.command ?? resource;
     class ResourceDiff extends DiffCommand {
         static args = {
             path: Args.string({ description: `Path to ${options.pathNoun} (overrides project config)` }),
@@ -156,9 +158,9 @@ export function resourceDiffCommand(resource, options) {
         static description = options.description;
         static enableJsonFlag = true;
         static examples = [
-            `$ lps ${resource} diff`,
-            `$ lps ${resource} diff --env staging`,
-            `$ lps ${resource} diff --env staging --against production`,
+            `$ lps ${command} diff`,
+            `$ lps ${command} diff --env staging`,
+            `$ lps ${command} diff --env staging --against production`,
         ];
         static flags = { ...DiffCommand.againstFlag };
         async run() {

package/dist/lib/diff-state.js

@@ -29,6 +29,7 @@ function renderTextChange(id, left, right, labels) {
 function objectFieldChanges(left, right) {
     return microdiff(left, right, { cyclesFix: false }).map((change) => {
         const path = change.path.join('.');
+        // microdiff types leaf values as `any`.
         if (change.type === 'CREATE')
             return { kind: 'added', path, to: change.value };
         if (change.type === 'REMOVE')

package/dist/lib/github-release.js

@@ -5,7 +5,6 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 const REPO = 'loopress/loopress';
-const RELEASE_TAG_PATTERN = /^wordpress-plugin@/;
 const ASSET_NAME = 'loopress-full.zip';
 /**
  * Downloads `loopress-full.zip` from the most recent `wordpress-plugin@*` release of

package/dist/lib/local-callback-server.d.ts

@@ -1,5 +1,4 @@
 export type CallbackHelpers<T> = {
-    body: Record<string, string>;
     rejectWithPage: (page: string, error: Error) => void;
     resolveWithPage: (page: string, value: T) => void;
     respondBadRequest: (message: string) => void;
@@ -9,13 +8,14 @@ export type CallbackHelpers<T> = {
  * 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:
+ * could otherwise send 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.
+ *   back (constant-time compare) on any request with a query string, the only place credentials
+ *   are read from;
+ * - an `Origin` allowlist: the legitimate callbacks are top-level redirects, which send no
+ *   `Origin`, so a request from a page script (carrying its own origin) is rejected. That's
+ *   defense in depth, `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.
@@ -23,12 +23,18 @@ export type CallbackHelpers<T> = {
 export declare function waitForLocalCallback<T>(options: {
     allowedOrigins: string[];
     buildUrl: (callbackBaseUrl: string, state: string) => string;
+    /** Host advertised in the callback URL; the server itself always listens on 127.0.0.1. */
+    callbackHost?: string;
     handleRequest: (url: URL, helpers: CallbackHelpers<T>) => void;
     log: (message: string) => void;
     openingMessage: string;
     timeoutMessage: string;
     timeoutMs?: number;
 }): Promise<T>;
+/**
+ * The page rewrites its own URL to `/` on load, so the callback query string (an Application
+ * Password, a console token) doesn't stay in the browser history or address bar.
+ */
 export declare function renderResultPage(options: {
     background: string;
     heading: string;