@loopress/cli 0.33.0 → 0.35.0

package/dist/lib/declared-plugins.js

@@ -0,0 +1,21 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseComposerJson, wpackagistRequire } from '../utils/composer.js';
+import {} from '../utils/loopress-config.js';
+import { isLocalEnvironment } from './wp-client.js';
+// The wordpress.org plugins the project declares: composer.json's wpackagist plugins when it
+// exists, loopress.json's otherwise. Unreadable or invalid composer.json: none, the commands
+// report it.
+export async function declaredPlugins(options) {
+    const path = resolve(process.cwd(), options.rootDir, 'composer.json');
+    if (!existsSync(path))
+        return { fromComposer: false, plugins: Object.keys(options.localConfig.plugins ?? {}) };
+    try {
+        const composerJson = parseComposerJson(await readFile(path, 'utf8'));
+        return { fromComposer: true, plugins: Object.keys(wpackagistRequire(composerJson, 'plugin', isLocalEnvironment(options.siteName))) };
+    }
+    catch {
+        return { fromComposer: true, plugins: [] };
+    }
+}

package/dist/lib/declared-type-command.js

@@ -46,6 +46,9 @@ export function declaredPushCommand(spec, description) {
                 parse: (raw, filePath) => parseDeclaredFile(spec, filePath, raw),
             });
             this.log(`Found ${pluralize(items.length, spec.noun, spec.plural)} to push`);
+            // Patterns carry block markup, the other declared types only registration arguments.
+            if (spec.cliName === 'pattern')
+                this.warnEnvironmentUrls(items.map((item) => ({ id: `${spec.plural}/${item.slug}`, value: item.args })));
             const pushed = [];
             await this.runPushTasks(items, (item) => item.slug, async (item, task) => {
                 await this.pushItem(item, task);

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

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

package/dist/lib/dev-watch.js

@@ -2,12 +2,10 @@ import { existsSync } from 'node:fs';
 import { join, sep } from 'node:path';
 import {} from '../utils/loopress-config.js';
 import { resolveResourceDir } from '../utils/resource-dirs.js';
-export const RESOURCE_TYPES = ['snippets', 'templates', 'parts', 'css', 'blocks', '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.
+import { selectResources } from './resource-selection.js';
+export const RESOURCE_TYPES = ['snippet', 'template', 'part', 'css', 'block', 'page', 'api', 'hook', 'plugin'];
 export function resolveResourceTypes(only, skip = []) {
-    const base = only && only.length > 0 ? only : RESOURCE_TYPES;
-    return base.filter((type) => !skip.includes(type));
+    return selectResources(RESOURCE_TYPES, only, skip);
 }
 // One target per requested type that actually has something to watch: a missing directory (no
 // `api/` folder yet) or an empty plugin manifest is left out silently, matching `push`'s own
@@ -17,19 +15,19 @@ export function buildWatchTargets(types, localConfig, cwd) {
     const candidates = {
         api: { commandId: 'api:push', path: join(cwd, resolveResourceDir('api', localConfig)), type: 'api' },
         // The theme CSS is bundled into the child theme with the templates, by the same push.
-        blocks: { commandId: 'theme:template:push', path: join(cwd, resolveResourceDir('blockCss', localConfig)), type: 'blocks' },
+        block: { commandId: 'theme:template:push', path: join(cwd, resolveResourceDir('blockCss', localConfig)), type: 'block' },
         css: { commandId: 'theme:template:push', path: join(cwd, resolveResourceDir('css', localConfig)), type: 'css' },
-        hooks: { commandId: 'hook:push', path: join(cwd, resolveResourceDir('hooks', localConfig)), type: 'hooks' },
-        pages: { commandId: 'page:push', path: join(cwd, resolveResourceDir('page', localConfig)), type: 'pages' },
-        plugins: { commandId: 'plugin:push', path: join(cwd, 'loopress.json'), type: 'plugins' },
-        parts: { commandId: 'theme:template:push', path: join(cwd, resolveResourceDir('part', localConfig)), type: 'parts' },
-        templates: { commandId: 'theme:template:push', path: join(cwd, resolveResourceDir('template', localConfig)), type: 'templates' },
-        snippets: { commandId: 'snippet:push', path: join(cwd, resolveResourceDir('snippets', localConfig)), type: 'snippets' },
+        hook: { commandId: 'hook:push', path: join(cwd, resolveResourceDir('hooks', localConfig)), type: 'hook' },
+        page: { commandId: 'page:push', path: join(cwd, resolveResourceDir('page', localConfig)), type: 'page' },
+        plugin: { commandId: 'plugin:push', path: join(cwd, 'loopress.json'), type: 'plugin' },
+        part: { commandId: 'theme:template:push', path: join(cwd, resolveResourceDir('part', localConfig)), type: 'part' },
+        template: { commandId: 'theme:template:push', path: join(cwd, resolveResourceDir('template', localConfig)), type: 'template' },
+        snippet: { commandId: 'snippet:push', path: join(cwd, resolveResourceDir('snippets', localConfig)), type: 'snippet' },
     };
     return types
         .map((type) => candidates[type])
         .filter((target) => {
-        if (target.type === 'plugins')
+        if (target.type === 'plugin')
             return Object.keys(localConfig.plugins ?? {}).length > 0;
         return existsSync(target.path);
     });

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

@@ -1,4 +1,5 @@
 import { LoopressCommand } from './base.js';
+import { type MissingIntegration } from './capabilities.js';
 import { type ResourceState, type StateChange } from './diff-state.js';
 import { type ResourceStateProvider } from './resource-state.js';
 import { WpClient } from './wp-client.js';
@@ -6,7 +7,10 @@ export type ResourceDiffJson = {
     added: string[];
     changed: StateChange[];
     error?: string;
+    heldBack?: string[];
+    reason?: string;
     removed: string[];
+    status?: 'skipped';
 };
 export type DiffJson = {
     drift: boolean;
@@ -15,11 +19,18 @@ export type DiffJson = {
     right: string;
 };
 export type DiffTarget = {
+    heldBackFrom?: (() => Promise<ResourceState>) | undefined;
+    isHeldBack?: ((id: string) => boolean) | undefined;
     left: () => Promise<ResourceState>;
     resource: string;
     right: () => Promise<ResourceState>;
     skip?: boolean;
     title: string;
+    unsupported?: {
+        fix?: string | undefined;
+        missing: MissingIntegration;
+        reason: string;
+    };
 };
 export type DiffSides = {
     againstWp: undefined | WpClient;
@@ -32,15 +43,19 @@ export declare abstract class DiffCommand extends LoopressCommand {
     static againstFlag: {
         against: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
+    static honorsExclude: boolean;
     protected composerTarget(sides: DiffSides): DiffTarget;
     protected providerTarget(provider: ResourceStateProvider, sides: DiffSides, dirOverride?: string): DiffTarget;
     protected report(targets: DiffTarget[], sides: DiffSides): Promise<DiffJson>;
+    protected reportDrift(result: DiffJson): Promise<void>;
     protected resolveSides(against: string | undefined): DiffSides;
     abstract run(): Promise<DiffJson>;
     private computeResource;
     private out;
     private renderFailure;
+    private renderHeldBack;
     private renderSection;
+    private renderSkipped;
     private wpForEnvironment;
 }
 export declare function resourceDiffCommand(resource: string, options: {
@@ -48,3 +63,5 @@ export declare function resourceDiffCommand(resource: string, options: {
     description: string;
     pathNoun: string;
 }): typeof DiffCommand;
+export declare function excludedFileFor(dir: string, id: string, provider: Pick<ResourceStateProvider, 'fileExtension' | 'fileName'>): boolean;
+export declare function sharedReads(wp: WpClient): WpClient;

package/dist/lib/diff-command.js

@@ -1,9 +1,15 @@
 import { Args, Flags, ux } from '@oclif/core';
-import { resolve } from 'node:path';
+import got from 'got';
+import { join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { authManager } from '../config/auth.manager.js';
 import { configManager } from '../config/project-config.manager.js';
 import { resolveResourceDir } from '../utils/resource-dirs.js';
+import { API_URL } from './api-client.js';
 import { LoopressCommand } from './base.js';
+import {} from './capabilities.js';
 import { compareStates, isEmptyDiff } from './diff-state.js';
+import { hasExclusions, isExcluded, withoutExclusions } from './exclude.js';
 import { errorMessage } from './narrow.js';
 import { composerLocalState, composerRemoteState, getResourceStateProvider } from './resource-state.js';
 import { WpClient } from './wp-client.js';
@@ -18,6 +24,7 @@ export class DiffCommand extends LoopressCommand {
             description: 'Compare the primary environment against this second environment instead of against local files',
         }),
     };
+    static honorsExclude = true;
     composerTarget(sides) {
         // resolve(), not join(): an absolute `rootDir` in loopress.json must stay absolute rather
         // than being prefixed with the cwd, so Composer is read from the same place as the
@@ -39,10 +46,18 @@ export class DiffCommand extends LoopressCommand {
         }
         const dir = resolveResourceDir(provider.dirKind, this.localConfig, dirOverride);
         const { againstWp } = sides;
+        const holdsBack = againstWp === undefined && hasExclusions();
+        // With exclusions, the local side may read the site too (an excluded file keeps the site's
+        // copy): both sides then share one response, so a site change between two reads can't show
+        // up as drift.
+        const wp = holdsBack ? sharedReads(this.wp) : this.wp;
         return {
-            left: async () => provider.remote(this.wp, sides.warn, dir),
+            // Only against local files: they are what an exclude glob names.
+            heldBackFrom: holdsBack ? async () => withoutExclusions(async () => provider.local(dir, () => { }, wp)) : undefined,
+            isHeldBack: holdsBack ? (id) => excludedFileFor(dir, id, provider) : undefined,
+            left: async () => provider.remote(wp, sides.warn, dir),
             resource: provider.resource,
-            right: againstWp ? async () => provider.remote(againstWp, sides.warn, dir) : async () => provider.local(dir, sides.warn, this.wp),
+            right: againstWp ? async () => provider.remote(againstWp, sides.warn, dir) : async () => provider.local(dir, sides.warn, wp),
             title: provider.title,
         };
     }
@@ -84,20 +99,49 @@ export class DiffCommand extends LoopressCommand {
             if (result.drift)
                 drift = true;
         }
+        this.renderHeldBack(checked, sides.leftLabel);
         const skipped = results.filter((result) => result.skipped);
-        for (const result of skipped)
-            this.out(`${c('bold', result.title)}  ${c('dim', 'not configured, skipped')}`);
+        const unsupported = this.renderSkipped(skipped, resources);
         this.out(`\n${compared} compared: ${changed} changed, ${added} added, ${removed} removed`);
         if (failed)
             this.out(c('red', 'Some resources could not be compared; this run is inconclusive.'));
         else
             this.out(drift ? c('yellow', 'Drift detected.') : c('green', 'Everything is in sync.'));
+        if (unsupported.length > 0)
+            this.warn(`Skipped with --skip-unsupported, not compared:\n  ${unsupported.join('\n  ')}`);
         if (failed)
             process.exitCode = 2;
         else if (drift)
             process.exitCode = 1;
         return { drift, left: sides.leftLabel, resources, right: sides.rightLabel };
     }
+    // Best-effort, like `recordDeployment`: when a token is present, sends the console the verdict
+    // and the changed items (resource, id, change kind, never contents). Silent on any failure, and
+    // it never touches the exit code or the `--json` output.
+    async reportDrift(result) {
+        const items = Object.entries(result.resources).flatMap(([resource, diff]) => [
+            ...diff.added.map((id) => ({ change: 'added', id, resource })),
+            ...diff.removed.map((id) => ({ change: 'removed', id, resource })),
+            ...diff.changed.map(({ id }) => ({ change: 'changed', id, resource })),
+        ]);
+        const inconclusive = Object.values(result.resources).some((diff) => diff.error !== undefined);
+        let status = result.drift ? 'drift' : 'clean';
+        if (inconclusive)
+            status = 'inconclusive';
+        try {
+            const token = process.env.LOOPRESS_TOKEN ?? authManager.getAuth()?.token ?? null;
+            if (!token)
+                return;
+            await got.post(`${API_URL}/drift-reports`, {
+                headers: { Authorization: `Bearer ${token}` },
+                json: { exitCode: process.exitCode ?? 0, items, status, url: this.siteConfig.url },
+                timeout: { request: 3000 },
+            });
+        }
+        catch {
+            // non-blocking: reporting must never change the diff's outcome
+        }
+    }
     resolveSides(against) {
         if (against === this.siteConfig.name) {
             this.error('--against must be a different environment from the one being compared.');
@@ -117,13 +161,24 @@ export class DiffCommand extends LoopressCommand {
     async computeResource(target, sides) {
         const empty = { added: [], changed: [], removed: [] };
         if (target.skip)
-            return { drift: false, json: empty, resource: target.resource, skipped: true, title: target.title };
+            return { drift: false, json: empty, resource: target.resource, skipped: true, title: target.title, unsupported: target.unsupported };
         try {
-            const [leftState, rightState] = await Promise.all([target.left(), target.right()]);
+            const [leftState, rightState, fullState] = await Promise.all([target.left(), target.right(), target.heldBackFrom?.()]);
+            // Whole items: only in the unfiltered local files, or only on the site under an excluded path.
+            const heldBackItems = [
+                ...(fullState ? [...fullState.keys()].filter((id) => !rightState.has(id)) : []),
+                ...[...leftState.keys()].filter((id) => !rightState.has(id) && !fullState?.has(id) && target.isHeldBack?.(id) === true),
+            ];
+            for (const id of heldBackItems)
+                leftState.delete(id);
+            // An item an excluded file is part of (a block's view.js): compared with the site's copy of
+            // that file, held back when the local one differs.
+            const heldBackFiles = fullState ? [...rightState.keys()].filter((id) => fullState.has(id) && !isDeepStrictEqual(fullState.get(id), rightState.get(id))) : [];
+            const heldBack = [...heldBackItems, ...heldBackFiles].toSorted((a, b) => a.localeCompare(b));
             const stateDiff = compareStates(leftState, rightState, { left: sides.leftLabel, right: sides.rightLabel });
             return {
                 drift: !isEmptyDiff(stateDiff),
-                json: { added: stateDiff.added, changed: stateDiff.changed, removed: stateDiff.removed },
+                json: { added: stateDiff.added, changed: stateDiff.changed, removed: stateDiff.removed, ...(heldBack.length > 0 && { heldBack }) },
                 resource: target.resource,
                 stateDiff,
                 title: target.title,
@@ -145,6 +200,16 @@ export class DiffCommand extends LoopressCommand {
         const errorLabel = c('red', `error: ${error}`);
         this.out(`${c('bold', title)}  ${errorLabel}`);
     }
+    // Its own group, after the comparison: excluded items are never drift, but a feature held back
+    // from an environment must stay visible there.
+    renderHeldBack(results, envName) {
+        const held = results.filter((result) => (result.json.heldBack ?? []).length > 0);
+        if (held.length === 0)
+            return;
+        this.out(c('bold', `\nHeld back from ${envName} (exclude in loopress.json), not compared`));
+        for (const result of held)
+            this.out(c('dim', `  ${result.title}: ${(result.json.heldBack ?? []).join(', ')}`));
+    }
     renderSection(title, stateDiff) {
         if (isEmptyDiff(stateDiff)) {
             this.out(`${c('bold', title)}  ${c('dim', 'in sync')}`);
@@ -160,6 +225,24 @@ export class DiffCommand extends LoopressCommand {
             this.out(indentPatch(change.patch));
         }
     }
+    // The skipped resources' lines. Returns the --skip-unsupported ones for the final warning, and
+    // adds them to the JSON result as skipped, with their reason.
+    renderSkipped(skipped, resources) {
+        const warnings = [];
+        for (const { resource, title, unsupported } of skipped) {
+            if (!unsupported) {
+                this.out(`${c('bold', title)}  ${c('dim', 'not configured, skipped')}`);
+                continue;
+            }
+            const { fix, reason } = unsupported;
+            resources[resource] = { added: [], changed: [], reason, removed: [], status: 'skipped' };
+            const note = `${reason}, skipped (--skip-unsupported)`;
+            this.out(`${c('bold', title)}  ${c('dim', note)}`);
+            const fixSentence = fix ? ` ${fix}.` : '';
+            warnings.push(`${title}: ${reason}.${fixSentence}`);
+        }
+        return warnings;
+    }
     wpForEnvironment(envName) {
         const env = configManager.getEnvironment(this.projectId, envName);
         if (!env) {
@@ -173,7 +256,7 @@ export class DiffCommand extends LoopressCommand {
 }
 // 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).
+// `command` is the CLI topic when it isn't the resource key (e.g. `theme style` for theme-style).
 export function resourceDiffCommand(resource, options) {
     const command = options.command ?? resource;
     class ResourceDiff extends DiffCommand {
@@ -196,6 +279,19 @@ export function resourceDiffCommand(resource, options) {
     }
     return ResourceDiff;
 }
+// The id is the file's path under the resource directory for most resources (a slug, an API
+// route), without its extension: a provider whose ids don't follow that names the file itself
+// (`fileName`), one with an extension is tried with it only, and one without (a block folder)
+// with the bare path and every extension resource files use.
+const RESOURCE_FILE_EXTENSIONS = ['.json', '.php', '.html'];
+export function excludedFileFor(dir, id, provider) {
+    if (provider.fileName) {
+        const fileName = provider.fileName(id);
+        return fileName !== undefined && isExcluded(join(dir, fileName));
+    }
+    const extensions = provider.fileExtension === undefined ? ['', ...RESOURCE_FILE_EXTENSIONS] : [provider.fileExtension];
+    return extensions.some((extension) => isExcluded(join(dir, `${id}${extension}`)));
+}
 // Indents an already-formatted change block (a per-field list or a header-less unified diff)
 // so it sits visually under the `~ id` line.
 function indentPatch(patch) {
@@ -211,3 +307,23 @@ function sharedFailure(errors) {
     const distinct = new Set(failures);
     return failures.length > 1 && distinct.size === 1 ? failures[0] : undefined;
 }
+// A client whose plain GETs are read once per path and shared, for the lifetime of one
+// resource comparison. Every other call goes to `wp` unchanged.
+export function sharedReads(wp) {
+    const reads = new Map();
+    // `Object.create` keeps every other WpClient method, bound to `wp`'s own state.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- see above
+    const shared = Object.create(wp);
+    shared.get = async (path, options) => {
+        if (options !== undefined)
+            return wp.get(path, options);
+        let read = reads.get(path);
+        if (read === undefined) {
+            read = wp.get(path);
+            reads.set(path, read);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- the same path yields the same T
+        return read;
+    };
+    return shared;
+}

package/dist/lib/environment-urls.d.ts

@@ -0,0 +1,6 @@
+import { type EnvironmentConfig } from '../types/config.js';
+export type ScannedItem = {
+    id: string;
+    value: unknown;
+};
+export declare function environmentUrlWarnings(items: ScannedItem[], target: Pick<EnvironmentConfig, 'name' | 'url'>, environments: Array<Pick<EnvironmentConfig, 'name' | 'url'>>): string[];

package/dist/lib/environment-urls.js

@@ -0,0 +1,59 @@
+import {} from '../types/config.js';
+// `http(s)://` then the host, plain or JSON-escaped (`https:\/\/`), as block attributes and option
+// values can hold either.
+const ABSOLUTE_URL = /https?:(?:\/\/|\\\/\\\/)[^\s"'<>()\\]+/gi;
+// Warns, never rewrites: an absolute URL whose host is another environment of the project keeps
+// pointing there once pushed (a staging link on production). A relative path, a link to the
+// target environment itself and an external link are left alone.
+export function environmentUrlWarnings(items, target, environments) {
+    const others = otherEnvironmentHosts(target, environments);
+    if (others.size === 0)
+        return [];
+    return items.flatMap((item) => [...urlsByHost(item.value, others)].map(([host, urls]) => `${item.id} links to the "${others.get(host)}" environment (${host}), it will still point there on ${target.name}: ${[...urls].join(', ')}. ` +
+        'Use a relative path (/about) instead.'));
+}
+// Host (with its port, so two local sites on one machine stay apart) to environment name.
+function otherEnvironmentHosts(target, environments) {
+    const targetHost = hostOf(target.url);
+    const others = new Map();
+    for (const env of environments) {
+        const host = hostOf(env.url);
+        if (host !== undefined && host !== targetHost && !others.has(host))
+            others.set(host, env.name);
+    }
+    return others;
+}
+function urlsByHost(value, hosts) {
+    const found = new Map();
+    for (const text of strings(value)) {
+        for (const match of text.matchAll(ABSOLUTE_URL)) {
+            const url = match[0].replaceAll(String.raw `\/`, '/');
+            const host = hostOf(url);
+            if (host === undefined || !hosts.has(host))
+                continue;
+            found.set(host, (found.get(host) ?? new Set()).add(url));
+        }
+    }
+    return found;
+}
+function hostOf(url) {
+    try {
+        return new URL(url).host.toLowerCase() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function* strings(value) {
+    if (typeof value === 'string') {
+        yield value;
+    }
+    else if (Array.isArray(value)) {
+        for (const entry of value)
+            yield* strings(entry);
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const entry of Object.values(value))
+            yield* strings(entry);
+    }
+}

package/dist/lib/exclude.d.ts

@@ -0,0 +1,16 @@
+import { type LoopressLocalConfig } from '../utils/loopress-config.js';
+export declare function environmentExcludes(config: LoopressLocalConfig, envName: string): string[];
+export declare function activateExclusions(options: {
+    config: LoopressLocalConfig;
+    cwd: string;
+    envName: string;
+    honors: boolean;
+}): void;
+export declare function disableExclusions(): void;
+export declare function hasExclusions(): boolean;
+export declare function isExcluded(path: string): boolean;
+export declare function withoutExcluded<T>(dir: string, entries: T[], name: (entry: T) => string): T[];
+export declare function heldBackPaths(): string[];
+export declare function withoutExclusions<T>(fn: () => Promise<T>): Promise<T>;
+export declare function matchesAny(matchers: RegExp[], segments: string[]): boolean;
+export declare function globToRegExp(glob: string): RegExp;

package/dist/lib/exclude.js

@@ -0,0 +1,102 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import {} from '../utils/loopress-config.js';
+let active;
+// `lps dev` runs the per-resource pushes itself: it disables exclusions for its whole process.
+let disabled = false;
+// Paths (relative to rootDir) the listing layer hid since the active set was installed, for a
+// dry run to list them.
+const heldBack = new Set();
+// Inside `withoutExclusions`: every file is listed, to tell which items a filter held back.
+const suspended = new AsyncLocalStorage();
+export function environmentExcludes(config, envName) {
+    const excludes = config.environments?.[envName]?.exclude;
+    return Array.isArray(excludes) ? excludes.filter((pattern) => typeof pattern === 'string' && pattern.trim() !== '') : [];
+}
+// Called by every LoopressCommand's init: installs the environment's exclusions when the command
+// honors them, clears whatever a previous command of the same process installed otherwise.
+export function activateExclusions(options) {
+    heldBack.clear();
+    const patterns = !disabled && options.honors ? environmentExcludes(options.config, options.envName) : [];
+    active =
+        patterns.length === 0
+            ? undefined
+            : { matchers: patterns.map((pattern) => globToRegExp(pattern)), root: resolve(options.cwd, options.config.rootDir ?? '.') };
+}
+export function disableExclusions() {
+    disabled = true;
+    active = undefined;
+}
+export function hasExclusions() {
+    return active !== undefined;
+}
+// `path` is a file or a directory, absolute or relative to the cwd. A glob matching one of its
+// parent directories covers it too (`hooks/feature` excludes everything under it).
+export function isExcluded(path) {
+    if (!active || suspended.getStore())
+        return false;
+    const rel = relative(active.root, resolve(path));
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        return false;
+    return matchesAny(active.matchers, rel.split(sep));
+}
+// Drops the excluded entries of a listing of `dir` (entries relative to it) and records them.
+export function withoutExcluded(dir, entries, name) {
+    if (!active || suspended.getStore())
+        return entries;
+    const { root } = active;
+    return entries.filter((entry) => {
+        const path = resolve(dir, name(entry));
+        if (!isExcluded(path))
+            return true;
+        heldBack.add(relative(root, path).split(sep).join('/'));
+        return false;
+    });
+}
+export function heldBackPaths() {
+    return [...heldBack].toSorted((a, b) => a.localeCompare(b));
+}
+// Runs `fn` with every file listed, excluded ones included.
+export async function withoutExclusions(fn) {
+    return suspended.run(true, fn);
+}
+// Every pattern matched against a '/'-split relative path, or any of its parent directories.
+export function matchesAny(matchers, segments) {
+    for (let { length } = segments; length > 0; length--) {
+        const candidate = segments.slice(0, length).join('/');
+        if (matchers.some((matcher) => matcher.test(candidate)))
+            return true;
+    }
+    return false;
+}
+// `**` any number of directories, `*` anything but '/', `?` one character but '/'. A leading
+// `./` is ignored, the rest is literal.
+export function globToRegExp(glob) {
+    let source = glob.trim().replace(/^\.\//, '');
+    while (source.endsWith('/'))
+        source = source.slice(0, -1);
+    let pattern = '';
+    for (let i = 0; i < source.length; i++) {
+        const char = source.charAt(i);
+        if (char === '*' && source.charAt(i + 1) === '*') {
+            i += 1;
+            if (source.charAt(i + 1) === '/') {
+                i += 1;
+                pattern += '(?:.*/)?';
+            }
+            else {
+                pattern += '.*';
+            }
+        }
+        else if (char === '*') {
+            pattern += '[^/]*';
+        }
+        else if (char === '?') {
+            pattern += '[^/]';
+        }
+        else {
+            pattern += char.replaceAll(/[$()+.[\\\]^{|}]/g, String.raw `\$&`);
+        }
+    }
+    return new RegExp(`^${pattern}$`);
+}

package/dist/lib/load-snippets.js

@@ -2,6 +2,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
 import {} from '../types/snippet.js';
 import { defaultLocationForType, parseInsertMethod, parseLocation, parseType, } from '../utils/snippet-format.js';
+import { withoutExcluded } from './exclude.js';
 import { errorCode, errorMessage, isRecord } from './narrow.js';
 const TYPE_BY_EXTENSION = {
     '.css': 'css',
@@ -68,14 +69,11 @@ async function readSidecar(metaPath) {
         throw new Error('not a JSON object');
     return meta;
 }
-// Shared by `snippet push` (pushes to the project's own WordPress site) and `snippet publish`
-// (publishes to the Loopress api as a shared source): both read the same local `snippets/`
-// directory the same way. `onSkip` is optional so callers that don't care about per-file
-// warnings (e.g. `snippet publish`) can ignore them; skipped files are simply left out either way.
+// Reads the local `snippets/` directory. `onSkip` is optional: skipped files are simply left out either way.
 export async function loadSnippets(path, onSkip) {
     let files;
     try {
-        files = await readdir(path);
+        files = withoutExcluded(path, await readdir(path), (file) => file);
     }
     catch (error) {
         throw new Error(`Error loading snippets: ${errorMessage(error)}`, { cause: error });

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

@@ -11,6 +11,7 @@ import { resolveResourceDir, RESOURCE_DIR_DEFAULTS } from '../utils/resource-dir
 import { ApiClient } from './api-client.js';
 import { LoopressCommand } from './base.js';
 import {} from './diff-state.js';
+import { isExcluded } from './exclude.js';
 import { basenameKey, findOrphanedFiles } from './find-orphaned-files.js';
 import { isInteractive } from './interactive.js';
 import { loadFiles as loadDirectoryFiles } from './load-files.js';
@@ -119,7 +120,7 @@ export function resourcePushCommand(spec) {
             // 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))) : [];
+            const pruneList = flags.prune ? await this.resolvePruneList(new Set(files.map((file) => file.filename)), path) : [];
             if (this.dryRun) {
                 await this.writeAfterPushSnapshot(provider, path, beforeState);
                 return { changes: this.previewChanges, pruned: pruneList, pushed: files.map((file) => file.filename), status: 'dry-run' };
@@ -181,9 +182,10 @@ export function resourcePushCommand(spec) {
         // 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) {
+        // A file excluded from this environment (loopress.json) is left alone, never pruned.
+        async resolvePruneList(localFilenames, path) {
             const remote = await this.wp.get(spec.endpoint);
-            const orphans = remote.map((file) => file.filename).filter((name) => !localFilenames.has(name));
+            const orphans = remote.map((file) => file.filename).filter((name) => !localFilenames.has(name) && !isExcluded(join(path, `${name}.php`)));
             if (orphans.length === 0)
                 return [];
             const summary = `${pluralize(orphans.length, spec.noun)} on ${this.siteConfig.url} not present locally: ${orphans.join(', ')}`;