@loopress/cli 0.32.2 → 0.34.0

package/dist/lib/diff-command.js

@@ -1,10 +1,16 @@
 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 { INTEGRATION_MISSING } from './plugin-detection.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';
 const c = ux.colorize;
@@ -18,15 +24,17 @@ 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
         // file-backed resources.
         const localRoot = resolve(process.cwd(), this.rootDir);
+        const { againstWp } = sides;
         return {
             left: async () => composerRemoteState(this.wp),
             resource: 'composer',
-            right: sides.againstWp ? async () => composerRemoteState(sides.againstWp) : async () => composerLocalState(localRoot),
+            right: againstWp ? async () => composerRemoteState(againstWp) : async () => composerLocalState(localRoot),
             title: 'Composer',
         };
     }
@@ -37,10 +45,19 @@ export class DiffCommand extends LoopressCommand {
             this.error('A [PATH] argument cannot be combined with --against: --against compares two environments, not local files.');
         }
         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: sides.againstWp ? async () => provider.remote(sides.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,
         };
     }
@@ -82,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.');
@@ -113,22 +159,33 @@ export class DiffCommand extends LoopressCommand {
     // Fetches and compares one target. No output (so targets can run concurrently); `report`
     // renders `stateDiff` afterwards in a fixed order.
     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, 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,
             };
         }
         catch (error) {
-            const { message } = error;
-            const empty = { added: [], changed: [], removed: [] };
-            if (target.optional && INTEGRATION_MISSING.test(message))
-                return { drift: false, json: empty, resource: target.resource, skipped: true, title: target.title };
+            const message = errorMessage(error);
             return { drift: false, json: { ...empty, error: message }, resource: target.resource, title: target.title };
         }
     }
@@ -143,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')}`);
@@ -158,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) {
@@ -171,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 {
@@ -194,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) {
@@ -209,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/diff-state.js

@@ -1,11 +1,10 @@
 import { createTwoFilesPatch } from 'diff';
 import microdiff from 'microdiff';
 import { isDeepStrictEqual } from 'node:util';
+import { isRecord } from './narrow.js';
 const MAX_VALUE_LENGTH = 200;
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
 function formatValue(value) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- typed as string, but JSON.stringify returns undefined for `undefined` (a removed field)
     const text = JSON.stringify(value) ?? String(value);
     return text.length > MAX_VALUE_LENGTH ? `${text.slice(0, MAX_VALUE_LENGTH - 1)}…` : text;
 }

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-files.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
+import { errorMessage } from './narrow.js';
 import { readdirTolerant, walkFiles } from './readdir-tolerant.js';
 // Loads every `<extension>` file of a directory through `parse`. One file is read in
 // isolation: a corrupted or hand-broken file (unreadable, bad JSON, failed validation) must
@@ -15,7 +16,7 @@ export async function loadFiles(dir, options) {
             items.push(options.parse(await readFile(filePath, 'utf8'), filePath));
         }
         catch (error) {
-            options.onSkip(`Skipping "${filePath}": ${error.message}`);
+            options.onSkip(`Skipping "${filePath}": ${errorMessage(error)}`);
         }
     }
     return items;

package/dist/lib/load-snippets.js

@@ -1,6 +1,9 @@
 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',
     '.html': 'html',
@@ -21,58 +24,51 @@ async function loadSnippet(path, file, onSkip) {
         content = await readFile(filePath, 'utf8');
     }
     catch (error) {
-        onSkip?.(`Skipping "${filePath}": ${error.message}`);
+        onSkip?.(`Skipping "${filePath}": ${errorMessage(error)}`);
         return undefined;
     }
-    let id;
-    let name;
-    let description;
-    let type;
-    let isActive = false;
-    let tags = [];
-    let location = null;
-    let insertMethod = null;
-    let priority = 10;
-    let shortcodeAttributes = [];
+    let meta;
     try {
-        const metaContent = await readFile(metaPath, 'utf8');
-        const meta = JSON.parse(metaContent);
-        id = meta.id;
-        // `||`, not `??`: an empty-string name in the sidecar JSON counts as absent too.
-        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-        name = meta.name || undefined;
-        // Kept even when empty: a description cleared on purpose, not one to replace with "Imported from <path>".
-        description = meta.description;
-        type = parseType(meta.type) ?? undefined;
-        isActive = Boolean(meta.active);
-        tags = Array.isArray(meta.tags) ? meta.tags.map(String) : [];
-        location = parseLocation(meta.location);
-        insertMethod = parseInsertMethod(meta.insertMethod);
-        priority = meta.priority ?? 10;
-        shortcodeAttributes = Array.isArray(meta.shortcodeAttributes) ? meta.shortcodeAttributes.map(String) : [];
+        meta = await readSidecar(metaPath);
     }
     catch (error) {
-        if (error.code !== 'ENOENT') {
-            onSkip?.(`Skipping "${metaPath}": ${error.message}`);
-            return undefined;
-        }
+        onSkip?.(`Skipping "${metaPath}": ${errorMessage(error)}`);
+        return undefined;
     }
-    const resolvedType = type ?? (Object.hasOwn(TYPE_BY_EXTENSION, ext) ? TYPE_BY_EXTENSION[ext] : 'php');
+    const type = parseType(meta.type) ?? TYPE_BY_EXTENSION[ext] ?? 'php';
     return {
-        active: isActive,
+        active: Boolean(meta.active),
         code: content,
-        description,
-        id,
-        insertMethod: insertMethod ?? 'auto',
-        location: location ?? defaultLocationForType(resolvedType),
-        name: name ?? basename(file, ext),
+        // Kept even when empty: a description cleared on purpose, not one to replace with "Imported from <path>".
+        description: typeof meta.description === 'string' ? meta.description : undefined,
+        id: typeof meta.id === 'number' ? meta.id : undefined,
+        insertMethod: parseInsertMethod(meta.insertMethod) ?? 'auto',
+        location: parseLocation(meta.location) ?? defaultLocationForType(type),
+        // An empty-string name in the sidecar JSON counts as absent too.
+        name: typeof meta.name === 'string' && meta.name !== '' ? meta.name : basename(file, ext),
         path: filePath,
-        priority,
-        shortcodeAttributes,
-        tags,
-        type: resolvedType,
+        priority: typeof meta.priority === 'number' ? meta.priority : 10,
+        shortcodeAttributes: Array.isArray(meta.shortcodeAttributes) ? meta.shortcodeAttributes.map(String) : [],
+        tags: Array.isArray(meta.tags) ? meta.tags.map(String) : [],
+        type,
     };
 }
+// The sidecar's JSON object, or no fields when the snippet has no sidecar (yet).
+async function readSidecar(metaPath) {
+    let raw;
+    try {
+        raw = await readFile(metaPath, 'utf8');
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return {};
+        throw error;
+    }
+    const meta = JSON.parse(raw);
+    if (!isRecord(meta))
+        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
@@ -80,10 +76,10 @@ async function loadSnippet(path, file, onSkip) {
 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: ${error.message}`, { cause: error });
+        throw new Error(`Error loading snippets: ${errorMessage(error)}`, { cause: error });
     }
     const snippets = [];
     for (const file of files) {

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

@@ -94,7 +94,13 @@ export async function waitForLocalCallback(options) {
             reject(new Error(options.timeoutMessage));
         }, timeoutMs);
         server.listen(0, '127.0.0.1', () => {
-            const { port } = server.address();
+            const address = server.address();
+            // Only a pipe or a closed server has no AddressInfo, never a TCP listen that just succeeded.
+            if (address === null || typeof address === 'string') {
+                reject(new Error('The local callback server has no TCP port'));
+                return;
+            }
+            const { port } = address;
             const targetUrl = options.buildUrl(`http://${options.callbackHost ?? 'localhost'}:${port}`, state);
             options.log(options.openingMessage);
             options.log(`\nIf it doesn't open automatically, visit:\n${targetUrl}\n`);

package/dist/lib/narrow.d.ts

@@ -0,0 +1,5 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isOneOf<T extends string>(values: Iterable<T>, value: unknown): value is T;
+export declare function errorMessage(error: unknown): string;
+export declare function causeOf(error: unknown): unknown;
+export declare function errorCode(error: unknown): string | undefined;

package/dist/lib/narrow.js

@@ -0,0 +1,26 @@
+// Type guards for values that arrive as `unknown`: a caught error, a parsed JSON document.
+// Arrays pass isRecord, same as a bare `typeof value === 'object' && value !== null` check.
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+// Membership in a closed list of literals, narrowing `value` to that union.
+export function isOneOf(values, value) {
+    for (const candidate of values)
+        if (candidate === value)
+            return true;
+    return false;
+}
+// `.message` of anything thrown: an Error, or an object shaped like one (got and oclif errors
+// are both). Anything else is stringified rather than read as `undefined`.
+export function errorMessage(error) {
+    return isRecord(error) && typeof error.message === 'string' ? error.message : String(error);
+}
+// The error a rethrown one wraps (`new Error(message, {cause})`), e.g. the got error behind
+// WpClient's formatted one.
+export function causeOf(error) {
+    return isRecord(error) ? error.cause : undefined;
+}
+// Node's errno code ('ENOENT', 'EEXIST', ...) when the thrown value carries one.
+export function errorCode(error) {
+    return isRecord(error) && typeof error.code === 'string' ? error.code : undefined;
+}