@loopress/cli 0.33.0 → 0.35.0

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

@@ -1,6 +1,27 @@
 import { LoopressCommand } from './base.js';
 import { type ResourceState } from './diff-state.js';
+import { type ScannedItem } from './environment-urls.js';
 import { type ResourceStateProvider } from './resource-state.js';
+export type DeploymentStep = {
+    command: string;
+    status: 'failed' | 'pushed' | 'skipped';
+};
+type DeploymentPlugins = Array<{
+    active: boolean;
+    slug: string;
+    version: string;
+}>;
+export declare function startDeploymentCollector(): {
+    plugins?: DeploymentPlugins;
+};
+export declare function stopDeploymentCollector(): void;
+export declare function postDeployment(body: {
+    command: string | undefined;
+    plugins?: DeploymentPlugins;
+    status: 'failure' | 'success';
+    steps?: DeploymentStep[];
+    url: string;
+}): Promise<void>;
 export type PushChange = {
     id: string;
     status: 'changed' | 'created' | 'removed' | 'unchanged';
@@ -19,6 +40,7 @@ export declare abstract class PushCommand extends LoopressCommand {
         'production-confirmed': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
+    static honorsExclude: boolean;
     protected failedCount: number;
     protected previewChanges: PushChange[];
     protected previewStates?: {
@@ -28,6 +50,7 @@ export declare abstract class PushCommand extends LoopressCommand {
     private refusedByGuard;
     protected captureBeforePushState(provider: ResourceStateProvider, dir: string, writes?: (id: string) => boolean): Promise<ResourceState | undefined>;
     catch(err: Error): Promise<void>;
+    finally(error: Error | undefined): Promise<void>;
     protected guardProductionPush(): Promise<void>;
     init(): Promise<void>;
     protected previewRemote(provider: ResourceStateProvider, dir: string): Promise<ResourceState>;
@@ -40,6 +63,9 @@ 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 warnEnvironmentUrls(items: ScannedItem[]): void;
     protected writeAfterPushSnapshot(provider: ResourceStateProvider, dir: string, beforeState: ResourceState | undefined): Promise<void>;
     private guardOutsideEdits;
+    private pushedPlugins;
 }
+export {};

package/dist/lib/push-command.js

@@ -2,19 +2,64 @@ import { confirm } from '@inquirer/prompts';
 import { Flags } from '@oclif/core';
 import got from 'got';
 import { Listr } from 'listr2';
+import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { authManager } from '../config/auth.manager.js';
 import {} from '../types/config.js';
+import { pinActive, pinVersion } from '../types/plugin.js';
 import { API_URL } from './api-client.js';
 import { LoopressCommand } from './base.js';
 import {} from './diff-state.js';
+import { environmentUrlWarnings } from './environment-urls.js';
+import { heldBackPaths } from './exclude.js';
 import { guardProductionPush } from './guard-production-push.js';
 import { isInteractive } from './interactive.js';
 import { errorMessage } from './narrow.js';
 import {} from './resource-state.js';
 import { readSnapshot, recordToState, writeSnapshot } from './snapshot-store.js';
 import { withoutSpinner, withSpinner } from './spinner.js';
+// The Git state the deployment record carries: the HEAD commit and whether the working tree has
+// uncommitted changes. Empty outside a Git repository (or without git), so nothing is sent then.
+function gitState() {
+    try {
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- git is resolved from PATH like in every dev tool
+        const git = (args) => execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim();
+        const commit = git(['rev-parse', 'HEAD']);
+        if (!commit)
+            return {};
+        return { commit, dirty: git(['status', '--porcelain', '--untracked-files=normal']) !== '' };
+    }
+    catch {
+        return {};
+    }
+}
+// Set while `lps push` runs its steps in process: they hand over what they would have posted
+// instead of posting, so the run sends one record (and waits at most one timeout).
+let deploymentCollector;
+export function startDeploymentCollector() {
+    deploymentCollector = {};
+    return deploymentCollector;
+}
+export function stopDeploymentCollector() {
+    deploymentCollector = undefined;
+}
+// Best-effort: recording must never interrupt the push flow.
+export async function postDeployment(body) {
+    const token = process.env.LOOPRESS_TOKEN ?? authManager.getAuth()?.token ?? null;
+    if (!token)
+        return;
+    try {
+        await withSpinner('Recording the deployment', async () => got.post(`${API_URL}/deployments`, {
+            headers: { Authorization: `Bearer ${token}` },
+            json: { ...body, ...gitState() },
+            timeout: { request: 3000 },
+        }));
+    }
+    catch {
+        // non-blocking
+    }
+}
 export function pushChanges(local, remote, options = {}) {
     const changes = [...local.keys()]
         .filter((id) => options.writes?.(id) ?? true)
@@ -44,6 +89,7 @@ export class PushCommand extends LoopressCommand {
         }),
         'production-confirmed': Flags.boolean({ hidden: true }),
     };
+    static honorsExclude = true;
     failedCount = 0;
     // A dry run's per-item preview, set by captureBeforePushState: what the push would create,
     // change or leave as it is on the site.
@@ -101,6 +147,16 @@ export class PushCommand extends LoopressCommand {
         }
         await super.catch(err);
     }
+    // Lists what the environment's `exclude` globs (loopress.json) kept out of this push, so a
+    // feature held back from it is never forgotten there.
+    async finally(error) {
+        const paths = error ? [] : heldBackPaths();
+        if (paths.length > 0) {
+            const prefix = this.dryRun ? '[dry-run] ' : '';
+            this.log(`${prefix}Held back from ${this.siteConfig.name} (exclude in loopress.json): ${paths.join(', ')}`);
+        }
+        await super.finally(error);
+    }
     async guardProductionPush() {
         await guardProductionPush({
             dryRun: this.dryRun,
@@ -129,19 +185,14 @@ export class PushCommand extends LoopressCommand {
         }
     }
     async recordDeployment(status) {
-        const token = process.env.LOOPRESS_TOKEN ?? authManager.getAuth()?.token ?? null;
-        if (!token)
+        // Inside `lps push`, the steps only report the plugin inventory: the run posts one record.
+        if (deploymentCollector) {
+            const { plugins } = this.pushedPlugins(status);
+            if (plugins)
+                deploymentCollector.plugins = plugins;
             return;
-        try {
-            await withSpinner('Recording the deployment', async () => got.post(`${API_URL}/deployments`, {
-                headers: { Authorization: `Bearer ${token}` },
-                json: { status, url: this.siteConfig.url },
-                timeout: { request: 3000 },
-            }));
-        }
-        catch {
-            // non-blocking: recording must never interrupt the push flow
         }
+        await postDeployment({ command: this.id, status, url: this.siteConfig.url, ...this.pushedPlugins(status) });
     }
     async recordSuccess() {
         if (this.dryRun)
@@ -191,12 +242,19 @@ export class PushCommand extends LoopressCommand {
             })), { concurrent: false, exitOnError: false, renderer: this.jsonEnabled() ? 'silent' : 'default' }).run();
         });
     }
+    // Absolute URLs to another environment of the project in what this push sends: warned about,
+    // never rewritten, on a dry run too.
+    warnEnvironmentUrls(items) {
+        const prefix = this.dryRun ? '[dry-run] ' : '';
+        for (const warning of environmentUrlWarnings(items, this.siteConfig, this.projectEnvironments))
+            this.warn(`${prefix}${warning}`);
+    }
     // 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 form
-    // that gets a server-assigned id on create, a theme-styles push that only touches the
+    // that gets a server-assigned id on create, a theme-style 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.
@@ -273,6 +331,14 @@ export class PushCommand extends LoopressCommand {
         if (!(await confirm({ default: false, message: 'Overwrite those changes?' })))
             this.error('Aborted.');
     }
+    // The plugin inventory of a landed `plugin:push` (a full `lps push` runs it as a step), read from
+    // loopress.json: slug, pinned version and whether it must be active. Other commands send none.
+    pushedPlugins(status) {
+        if (status !== 'success' || this.id !== 'plugin:push')
+            return {};
+        const plugins = Object.entries(this.localConfig.plugins ?? {}).map(([slug, pin]) => ({ active: pinActive(pin), slug, version: pinVersion(pin) }));
+        return { plugins };
+    }
 }
 function sameEntry(left, right, id) {
     return left.has(id) === right.has(id) && isDeepStrictEqual(left.get(id), right.get(id));

package/dist/lib/readdir-tolerant.js

@@ -1,12 +1,15 @@
 import {} from 'node:fs';
 import { readdir, stat } from 'node:fs/promises';
-import { join, relative, sep } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
+import { withoutExcluded } from './exclude.js';
 import { errorCode } from './narrow.js';
 export async function readdirTolerant(dir, options) {
     try {
+        // Excluded paths (lib/exclude.ts) are hidden here, so every resource listing through this
+        // helper leaves them out of a push or a diff on the environment that excludes them.
         return options?.withFileTypes
-            ? await readdir(dir, { recursive: options.recursive, withFileTypes: true })
-            : await readdir(dir, { recursive: options?.recursive });
+            ? withoutExcluded(dir, await readdir(dir, { recursive: options.recursive, withFileTypes: true }), (entry) => resolve(entry.parentPath, entry.name))
+            : withoutExcluded(dir, await readdir(dir, { recursive: options?.recursive }), (entry) => entry);
     }
     catch (error) {
         if (errorCode(error) === 'ENOENT')

package/dist/lib/resource-selection.d.ts

@@ -0,0 +1,9 @@
+import { Flags } from '@oclif/core';
+export declare const RESOURCE_IDS: readonly ["plugin", "composer", "cpt", "taxonomy", "meta", "role", "acf", "api", "hook", "block", "form", "pattern", "template", "part", "css", "theme-style", "page", "menu", "option", "snippet"];
+export type ResourceId = (typeof RESOURCE_IDS)[number];
+export declare function selectionFlags(noun: string, valid: readonly string[]): {
+    only: ReturnType<typeof Flags.string>;
+    skip: ReturnType<typeof Flags.string>;
+};
+export declare function parseSelectionFlag(raw: string[] | undefined, flagName: 'only' | 'skip', valid: readonly string[], fail: (message: string) => never): string[];
+export declare function selectResources<T extends string>(all: readonly T[], only?: readonly string[], skip?: readonly string[]): T[];

package/dist/lib/resource-selection.js

@@ -0,0 +1,49 @@
+import { Flags } from '@oclif/core';
+// One singular id per resource, shared by every command taking `--only` / `--skip`
+// (`lps dev`, `lps diff`, `lps push`). Each command accepts the subset it can act on.
+export const RESOURCE_IDS = [
+    'plugin',
+    'composer',
+    'cpt',
+    'taxonomy',
+    'meta',
+    'role',
+    'acf',
+    'api',
+    'hook',
+    'block',
+    'form',
+    'pattern',
+    'template',
+    'part',
+    'css',
+    'theme-style',
+    'page',
+    'menu',
+    'option',
+    'snippet',
+];
+// Comma-separated or repeated: `--only a,b`, `--only a --only b`, or both.
+export function selectionFlags(noun, valid) {
+    return {
+        only: Flags.string({ description: `Only ${noun} these resources (comma-separated or repeated): ${valid.join(', ')}`, multiple: true }),
+        skip: Flags.string({ description: `${noun.charAt(0).toUpperCase()}${noun.slice(1)} every resource except these (comma-separated or repeated)`, multiple: true }),
+    };
+}
+// Splits the raw flag values and rejects any id outside `valid`.
+export function parseSelectionFlag(raw, flagName, valid, fail) {
+    return (raw ?? [])
+        .flatMap((value) => value.split(','))
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .map((value) => {
+        if (!valid.includes(value))
+            fail(`Unknown resource "${value}" in --${flagName}. Valid resources: ${valid.join(', ')}`);
+        return value;
+    });
+}
+// `only` narrows `all`, `skip` then removes from whatever that is, so a combined
+// `--only=a,b --skip=b` reads as: a, b, then drop b. The result always follows `all`'s order.
+export function selectResources(all, only = [], skip = []) {
+    return all.filter((id) => (only.length === 0 || only.includes(id)) && !skip.includes(id));
+}

package/dist/lib/resource-state.d.ts

@@ -3,6 +3,8 @@ import { type ResourceState } from './diff-state.js';
 import { type WpClient } from './wp-client.js';
 export type ResourceStateProvider = {
     dirKind: ResourceDirKind;
+    fileExtension?: string;
+    fileName?(id: string): string | undefined;
     local(dir: string, onWarn: (message: string) => void, wp?: WpClient): Promise<ResourceState>;
     remote(wp: WpClient, onWarn: (message: string) => void, dir: string): Promise<ResourceState>;
     resource: string;

package/dist/lib/resource-state.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { basename, join, relative, sep } from 'node:path';
 import { ACF_OBJECT_TYPES, acfEndpoint, acfNormalizeEndpoint, getAcfKey } from '../utils/acf-format.js';
-import { BLOCKS_ENDPOINT, formatBlockProblems, readLocalBlocks } from '../utils/block-format.js';
+import { blockFilesToPush, BLOCKS_ENDPOINT, excludedBlockFiles, formatBlockProblems, readLocalBlocks } from '../utils/block-format.js';
 import { CPT_SPEC, fileExtension, META_SPEC, parseDeclaredFile, PATTERN_SPEC, ROLE_SPEC, TAXONOMY_SPEC, } from '../utils/declared-type-format.js';
 import { FORM_ENDPOINT, getFormId } from '../utils/form-format.js';
 import { getMenuSlug, MENU_ENDPOINT, MENU_LOCATIONS_ENDPOINT } from '../utils/menu-format.js';
@@ -91,6 +91,7 @@ const snippetProvider = {
 // stance as form-format.ts.
 const formProvider = {
     dirKind: 'form',
+    fileExtension: '.json',
     async local(dir, onWarn) {
         const entries = await loadFiles(dir, {
             extension: '.json',
@@ -137,6 +138,7 @@ async function normalizeAcf(wp, type, objects) {
 }
 const acfProvider = {
     dirKind: 'acf',
+    fileExtension: '.json',
     async local(dir, onWarn, wp) {
         const state = new Map();
         for (const type of ACF_OBJECT_TYPES) {
@@ -182,6 +184,7 @@ function filesToState(files) {
 function phpFilesProvider(spec) {
     return {
         dirKind: spec.dirKind,
+        fileExtension: '.php',
         async local(dir, onWarn) {
             return filesToState(await loadFiles(dir, {
                 extension: '.php',
@@ -217,11 +220,17 @@ const hookProvider = phpFilesProvider({
 // resource, the same stance as pages: pushing would stop on it anyway.
 const blockProvider = {
     dirKind: 'block',
-    async local(dir) {
+    // A block is a folder: only the bare `blocks/<slug>` path names a site-only block.
+    fileExtension: '',
+    // A file the environment excludes inside a block folder keeps the site's copy, as the push
+    // sends it back: without `wp`, that file is just left out.
+    async local(dir, _onWarn, wp) {
         const { blocks, problems } = await readLocalBlocks(dir);
         if (problems.length > 0)
             throw new Error(formatBlockProblems(problems));
-        return new Map(blocks.map((block) => [block.slug, block.files]));
+        const withExcluded = wp !== undefined && blocks.some((block) => excludedBlockFiles(dir, block.slug).length > 0);
+        const site = withExcluded ? new Map((await wp.get(BLOCKS_ENDPOINT)).map((block) => [block.slug, block.files])) : undefined;
+        return new Map(blocks.map((block) => [block.slug, site ? blockFilesToPush(dir, block, site.get(block.slug)) : block.files]));
     },
     async remote(wp) {
         const blocks = await wp.get(BLOCKS_ENDPOINT);
@@ -271,6 +280,7 @@ async function childThemeState(wp, kind) {
 }
 const templateProvider = {
     dirKind: 'template',
+    fileExtension: '.html',
     async local(dir) {
         const { files, problems } = await readLocalHtmlFiles(dir, parseTemplateFile, TEMPLATE_SLUG_RULE);
         if (problems.length > 0)
@@ -283,6 +293,7 @@ const templateProvider = {
 };
 const partProvider = {
     dirKind: 'part',
+    fileExtension: '.html',
     async local(dir) {
         const { files, problems } = await readLocalHtmlFiles(dir, parsePartFile, TEMPLATE_SLUG_RULE);
         if (problems.length > 0)
@@ -311,6 +322,12 @@ function canonicalMenu(menu) {
 }
 const menuProvider = {
     dirKind: 'menu',
+    fileExtension: '.json',
+    fileName(id) {
+        if (id === MENU_LOCATIONS_FILE)
+            return `${id}.json`;
+        return id.startsWith('menu/') ? `${id.slice('menu/'.length)}.json` : undefined;
+    },
     async local(dir, onWarn) {
         const state = new Map();
         const entries = await loadFiles(dir, {
@@ -348,6 +365,7 @@ const menuProvider = {
 function declaredTypeProvider(spec, title) {
     return {
         dirKind: spec.dirKind,
+        fileExtension: fileExtension(spec),
         async local(dir, onWarn) {
             const entries = await loadFiles(dir, {
                 extension: fileExtension(spec),
@@ -377,6 +395,7 @@ const patternProvider = declaredTypeProvider(PATTERN_SPEC, 'Patterns');
 // sides so it can never itself show up as drift.
 const optionsProvider = {
     dirKind: 'options',
+    fileExtension: '.json',
     async local(dir, onWarn) {
         const entries = await loadFiles(dir, {
             extension: '.json',
@@ -422,6 +441,8 @@ const optionsProvider = {
 // individually rather than colliding on a single key.
 const themeStylesProvider = {
     dirKind: 'themeStyles',
+    fileExtension: '.json',
+    fileName: (stylesheet) => `${stylesheet}${THEME_STYLES_FILE_SUFFIX}`,
     async local(dir, onWarn) {
         const entries = await loadFiles(dir, {
             extension: '.json',
@@ -445,7 +466,7 @@ const themeStylesProvider = {
         const item = await wp.get(globalStylesEndpoint(id));
         return new Map([[stylesheet, canonicalGlobalStyles(item)]]);
     },
-    resource: 'theme-styles',
+    resource: 'theme-style',
     title: 'Theme styles',
 };
 export const RESOURCE_STATE_PROVIDERS = [

package/dist/lib/rollback-command.js

@@ -34,7 +34,7 @@ function indentPatch(patch) {
 // anything, this runs the equivalent of `lps <resource> diff` between the environment's current
 // state and the state the original push expected to leave behind, and requires explicit
 // confirmation (the same interactive/`--yes` shape as guardProductionPush) when they differ.
-// `command` is the CLI topic when it isn't the resource key (e.g. `theme style` for theme-styles).
+// `command` is the CLI topic when it isn't the resource key (e.g. `theme style` for theme-style).
 export function resourceRollbackCommand(resource, options) {
     const command = options.command ?? resource;
     class ResourceRollback extends LoopressCommand {

package/dist/lib/rollback-materialize.js

@@ -115,7 +115,7 @@ const MATERIALIZERS = {
     role: declaredType(ROLE_SPEC),
     snippet,
     taxonomy: declaredType(TAXONOMY_SPEC),
-    'theme-styles': themeStyles,
+    'theme-style': themeStyles,
 };
 // Writes a snapshot's state back to `dir` in the exact on-disk layout `<resource> pull` would
 // have produced, so the existing `<resource> push` command can push it unmodified: a rollback

package/dist/lib/validate-local.d.ts

@@ -6,5 +6,6 @@ export type ValidateResult = {
     checked: number;
     problems: Problem[];
     valid: boolean;
+    warnings: Problem[];
 };
 export declare function validateLocal(cwd: string): Promise<ValidateResult>;

package/dist/lib/validate-local.js

@@ -1,8 +1,8 @@
-import { readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { z } from 'zod';
 import { configManager } from '../config/project-config.manager.js';
-import { PLUGIN_PIN } from '../types/plugin.js';
+import { pinProblem } from '../types/plugin.js';
 import { readLocalBlocks } from '../utils/block-format.js';
 import { COMPOSER_JSON } from '../utils/composer.js';
 import { CPT_SPEC, declaredFileChecker, META_SPEC, PATTERN_SPEC, ROLE_SPEC, TAXONOMY_SPEC } from '../utils/declared-type-format.js';
@@ -11,23 +11,24 @@ import { readLocalHtmlFiles, readLocalPages } from '../utils/page-format.js';
 import { RESOURCE_DIR_DEFAULTS } from '../utils/resource-dirs.js';
 import { parseType } from '../utils/snippet-format.js';
 import { readLocalTemplates } from '../utils/template-format.js';
+import { globToRegExp, matchesAny } from './exclude.js';
 import { loadSnippets } from './load-snippets.js';
 import { errorCode, errorMessage, isRecord } from './narrow.js';
 import { API_FILES_RESOURCE, HOOK_FILES_RESOURCE, phpFileProblems } from './php-files-command.js';
 import { readdirTolerant } from './readdir-tolerant.js';
 // Directories holding one JSON document per resource. Snippets (code file plus JSON sidecar)
 // and api routes (`.php`, not JSON) are checked separately, options too (a stricter shape).
-const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'menuDir', 'themeStylesDir'];
+const JSON_RESOURCE_DIRS = ['acfDir', 'formDir', 'menuDir', 'themeStyleDir'];
 const DEFAULT_DIR = {
     acfDir: 'acf',
     apiDir: 'api',
     blockDir: RESOURCE_DIR_DEFAULTS.block,
     cptDir: 'cpt',
     formDir: 'forms',
-    hooksDir: 'hooks',
+    hookDir: 'hooks',
     menuDir: 'menus',
     metaDir: 'meta',
-    optionsDir: 'options',
+    optionDir: 'options',
     pageDir: 'pages',
     partDir: RESOURCE_DIR_DEFAULTS.part,
     patternDir: RESOURCE_DIR_DEFAULTS.pattern,
@@ -35,7 +36,7 @@ const DEFAULT_DIR = {
     snippetsDir: 'snippets',
     taxonomyDir: 'taxonomies',
     templateDir: RESOURCE_DIR_DEFAULTS.template,
-    themeStylesDir: 'theme',
+    themeStyleDir: 'theme',
 };
 // Inspects the local tracked files under `cwd` without contacting WordPress: JSON files parse
 // and have the right shape, snippet sidecars use a known type, `loopress.json` points at a
@@ -58,7 +59,7 @@ export async function validateLocal(cwd) {
     }
     // Same reader `option push` uses: a file missing "name", "autoload" or "value" is skipped
     // there with a warning, so it's a problem here.
-    checked += await checkJsonDir(resolve('optionsDir'), problems, parseLocalOption);
+    checked += await checkJsonDir(resolve('optionDir'), problems, parseLocalOption);
     checked += await checkJsonDir(resolve('cptDir'), problems, declaredFileChecker(CPT_SPEC));
     checked += await checkJsonDir(resolve('taxonomyDir'), problems, declaredFileChecker(TAXONOMY_SPEC));
     checked += await checkJsonDir(resolve('metaDir'), problems, declaredFileChecker(META_SPEC));
@@ -66,7 +67,7 @@ export async function validateLocal(cwd) {
     checked += await checkPatterns(resolve('patternDir'), problems);
     checked += await checkSnippets(resolve('snippetsDir'), problems);
     checked += await checkPhpDir(resolve('apiDir'), problems, 'API route file is empty', API_FILES_RESOURCE);
-    checked += await checkPhpDir(resolve('hooksDir'), problems, 'Hook file is empty', HOOK_FILES_RESOURCE);
+    checked += await checkPhpDir(resolve('hookDir'), problems, 'Hook file is empty', HOOK_FILES_RESOURCE);
     const blocks = await readLocalBlocks(resolve('blockDir'));
     checked += blocks.blocks.length;
     problems.push(...blocks.problems);
@@ -76,7 +77,65 @@ export async function validateLocal(cwd) {
     const templates = await readLocalTemplates(resolve('templateDir'), resolve('partDir'));
     checked += templates.templates.length + templates.parts.length + templates.problems.length;
     problems.push(...templates.problems);
-    return { checked, problems, valid: problems.length === 0 };
+    const warnings = await checkExcludes(localConfig, join(cwd, rootDir), problems);
+    return { checked, problems, valid: problems.length === 0, warnings };
+}
+// `environments.<name>.exclude` (lib/exclude.ts): a list of globs per environment. A glob that
+// matches no file is a warning, not a problem: likely a typo or a renamed file, so the feature it
+// was meant to hold back would reach that environment.
+async function checkExcludes(localConfig, root, problems) {
+    const { environments } = localConfig;
+    if (environments === undefined)
+        return [];
+    if (!isRecord(environments) || Array.isArray(environments)) {
+        problems.push({ file: 'loopress.json', message: '"environments" must be an object of environment name -> settings' });
+        return [];
+    }
+    const warnings = [];
+    let files;
+    for (const [name, settings] of Object.entries(environments)) {
+        const parsed = ENVIRONMENT_SETTINGS.safeParse(settings);
+        if (!parsed.success) {
+            problems.push({ file: 'loopress.json', message: `environments.${name} must be an object with an optional "exclude" list of glob strings` });
+            continue;
+        }
+        for (const pattern of parsed.data.exclude ?? []) {
+            files ??= await projectFiles(root);
+            const matcher = globToRegExp(pattern);
+            if (files.every((segments) => !matchesAny([matcher], segments))) {
+                warnings.push({ file: 'loopress.json', message: `environments.${name}.exclude: "${pattern}" matches no file` });
+            }
+        }
+    }
+    return warnings;
+}
+const ENVIRONMENT_SETTINGS = z.strictObject({ exclude: z.array(z.string()).optional() });
+// Every file under `root` as '/'-split segments, without node_modules and .git.
+async function projectFiles(root) {
+    const files = [];
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name !== 'node_modules' && entry.name !== '.git')
+                    await walk(path);
+            }
+            else {
+                files.push(relative(root, path).split(sep));
+            }
+        }
+    };
+    await walk(root);
+    return files;
 }
 // Same directory rules as pages (flat, .html only), then the same checks as `pattern push`.
 async function checkPatterns(dir, problems) {
@@ -200,9 +259,9 @@ function checkLoopressJson(localConfig, problems) {
     }
     for (const [slug, version] of Object.entries(manifest.data)) {
         // The object form is what `plugin pull` writes for a plugin installed but inactive (see PluginPin).
-        if (!PLUGIN_PIN.safeParse(version).success) {
-            problems.push({ file: 'loopress.json', message: `plugin "${slug}" must map to a version string or {version, active}` });
-        }
+        const message = pinProblem(slug, version);
+        if (message)
+            problems.push({ file: 'loopress.json', message });
     }
 }
 async function checkSnippets(dir, problems) {

package/dist/lib/wp-client.d.ts

@@ -24,6 +24,8 @@ type RequestOptions = {
 };
 export declare function isNotFoundError(error: unknown): boolean;
 export declare function isForbiddenError(error: unknown): boolean;
+export declare function isFirewallBlock(error: unknown): boolean;
+export declare function isApplicationPasswordsDisabled(error: unknown): boolean;
 export declare function isApplicative404(error: unknown, marker: string): boolean;
 export declare function isConflictCode(error: unknown, code: string): boolean;
 export declare function isTimeoutError(error: unknown): boolean;

package/dist/lib/wp-client.js

@@ -100,6 +100,23 @@ export function isNotFoundError(error) {
 export function isForbiddenError(error) {
     return responseOf(causeOf(error)).statusCode === 403;
 }
+// A 403 whose body is not a WordPress JSON error (`code`/`message`) nor a Loopress `error`
+// refusal: the answer of a firewall (ModSecurity, Imunify360, Wordfence...) in front of PHP.
+export function isFirewallBlock(error) {
+    return isFirewallResponse(responseOf(causeOf(error)));
+}
+function isFirewallResponse({ body, statusCode }) {
+    if (statusCode !== 403)
+        return false;
+    const parsed = parseBody(body);
+    return typeof parsed.code !== 'string' && typeof parsed.message !== 'string' && typeof parsed.error !== 'string';
+}
+// WordPress core answers the authenticated request with this `code` when Application
+// Passwords are turned off for the user (a security plugin, `wp_is_application_passwords_available`
+// filter or the user's role), as opposed to `incorrect_password`/`invalid_username` for bad credentials.
+export function isApplicationPasswordsDisabled(error) {
+    return parseBody(responseOf(causeOf(error)).body).code === 'application_passwords_disabled_for_user';
+}
 // A 404 a Loopress controller raises on purpose, identified by its JSON body's `error` field
 // (e.g. `{"error": "composer.lock not found"}` from ComposerController). Narrower than
 // isNotFoundError: a bare 404 also covers the route being absent because the plugin isn't
@@ -146,16 +163,8 @@ export function parseBody(body) {
 }
 export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     const { body, statusCode: status } = responseOf(error);
-    if (status === 401 || status === 403) {
-        // A Loopress controller's own `{"error": ...}` on a 403 is a deliberate refusal of this one
-        // request (e.g. OptionsController protecting a secret-looking option), not bad credentials:
-        // pointing at `lps project config` there sends the user the wrong way. WordPress core's own
-        // auth failures use `{code, message}` instead and keep the credentials hint.
-        const refusal = extractLoopressError(body);
-        if (refusal)
-            return `Request refused (${status}) on ${url}: ${refusal}`;
-        return `Authentication failed (${status}) on ${url}. Check your credentials with \`lps project config\`.`;
-    }
+    if (status === 401 || status === 403)
+        return formatAuthError(status, body, url);
     if (status === 404) {
         const reason = extractServerErrorMessage(body);
         return reason
@@ -180,6 +189,23 @@ export function formatWpError(error, url, timeoutMs = REQUEST_TIMEOUT_MS) {
     const message = isRecord(error) && typeof error.message === 'string' ? error.message : '';
     return `Request to ${url} failed: ${message || (code ?? String(error))}`;
 }
+function formatAuthError(status, body, url) {
+    if (isFirewallResponse({ body, statusCode: status }))
+        return firewallMessage(url);
+    // A Loopress controller's own `{"error": ...}` on a 403 is a deliberate refusal of this one
+    // request (e.g. OptionsController protecting a secret-looking option), not bad credentials:
+    // pointing at `lps project config` there sends the user the wrong way. WordPress core's own
+    // auth failures use `{code, message}` instead and keep the credentials hint.
+    const refusal = extractLoopressError(body);
+    if (refusal)
+        return `Request refused (${status}) on ${url}: ${refusal}`;
+    return `Authentication failed (${status}) on ${url}. Check your credentials with \`lps project config\`.`;
+}
+// A 403 that is not a WordPress JSON error never came from WordPress: a web application
+// firewall answered before PHP ran, and no credential change will fix it.
+function firewallMessage(url) {
+    return `Request blocked (403) on ${url}: the response is not a WordPress error, so a firewall or security plugin (ModSecurity, Imunify360, Wordfence) probably blocked the request. Allow-list the request or your IP in the firewall, then retry.`;
+}
 const NETWORK_ERROR_HINTS = {
     ECONNREFUSED: 'connection refused, the site may be down',
     ECONNRESET: 'connection reset by the server',