@loopress/cli 0.33.0 → 0.34.0

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',
@@ -75,7 +76,7 @@ async function readSidecar(metaPath) {
 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(', ')}`;

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

@@ -1,5 +1,6 @@
 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 PushChange = {
     id: string;
@@ -19,6 +20,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 +30,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 +43,7 @@ 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;
 }

package/dist/lib/push-command.js

@@ -2,6 +2,7 @@ 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';
@@ -9,12 +10,29 @@ import {} from '../types/config.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 {};
+    }
+}
 export function pushChanges(local, remote, options = {}) {
     const changes = [...local.keys()]
         .filter((id) => options.writes?.(id) ?? true)
@@ -44,6 +62,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 +120,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,
@@ -135,7 +164,7 @@ export class PushCommand extends LoopressCommand {
         try {
             await withSpinner('Recording the deployment', async () => got.post(`${API_URL}/deployments`, {
                 headers: { Authorization: `Bearer ${token}` },
-                json: { status, url: this.siteConfig.url },
+                json: { status, url: this.siteConfig.url, command: this.id, ...gitState() },
                 timeout: { request: 3000 },
             }));
         }
@@ -191,12 +220,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.

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')